@swarmclawai/swarmclaw 1.9.33 → 1.9.34

package/README.md

@@ -151,6 +151,15 @@ openclaw skills install swarmclaw
 
 [Browse on ClawHub](https://clawhub.ai/waydelyle/swarmclaw)
 
+## v1.9.34 Highlights
+
+Credential recovery and external extension access release for npm-global upgrades and scoped agent tool configuration.
+
+- **Credential secret recovery.** Startup now checks prior npm-global build env files before accepting a fresh per-version `CREDENTIAL_SECRET`, and validates candidate secrets against existing encrypted credentials before persisting `DATA_DIR/credential-secret`.
+- **Clear connector failures.** Connector startup now logs and surfaces credential decrypt failures directly instead of falling through to a misleading "No bot token configured" error.
+- **External extension tools.** Scoped agents now keep explicitly attached external `*.js` and `*.mjs` extensions, and the agent/chat tool controls persist enabled external tools through the `extensions` field.
+- **Regression coverage.** Added tests for previous-build credential recovery, non-decrypting secret replacement, scoped external extension access, and extension access persistence.
+
 ## v1.9.33 Highlights
 
 Issue and PR validation release for credential durability, delegated task dispatch, connector output hygiene, and OpenClaw gateway protocol compatibility.
@@ -445,6 +454,15 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.9.34 Highlights
+
+Credential recovery and external extension access release for npm-global upgrades and scoped agent tool configuration.
+
+- **Credential secret recovery.** Startup now checks prior npm-global build env files before accepting a fresh per-version `CREDENTIAL_SECRET`, and validates candidate secrets against existing encrypted credentials before persisting `DATA_DIR/credential-secret`.
+- **Clear connector failures.** Connector startup now logs and surfaces credential decrypt failures directly instead of falling through to a misleading "No bot token configured" error.
+- **External extension tools.** Scoped agents now keep explicitly attached external `*.js` and `*.mjs` extensions, and the agent/chat tool controls persist enabled external tools through the `extensions` field.
+- **Regression coverage.** Added tests for previous-build credential recovery, non-decrypting secret replacement, scoped external extension access, and extension access persistence.
+
 ### v1.9.33 Highlights
 
 Issue and PR validation release for credential durability, delegated task dispatch, connector output hygiene, and OpenClaw gateway protocol compatibility.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.33",
+  "version": "1.9.34",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",

package/src/app/api/extensions/builtins/route.ts

@@ -20,7 +20,7 @@ export async function GET() {
 
   // For external extensions that are enabled, also collect their concrete tool names
   // so the UI can show those tools in the toggles
-  const externalTools: Array<{ extensionId: string; toolName: string; label: string; description: string }> = []
+  const externalTools: Array<{ extensionId: string; extensionName: string; toolName: string; label: string; description: string }> = []
   for (const meta of all) {
     if (meta.isBuiltin || !meta.enabled) continue
     try {
@@ -28,6 +28,7 @@ export async function GET() {
       for (const entry of tools) {
         externalTools.push({
           extensionId: entry.extensionId,
+          extensionName: meta.name || meta.filename,
           toolName: entry.tool.name,
           label: entry.tool.name.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()),
           description: entry.tool.description || '',

package/src/components/agents/agent-sheet.tsx

@@ -57,6 +57,14 @@ const AUTO_SYNC_MODEL_PROVIDER_IDS = new Set<ProviderType>([
 const CONNECTION_TEST_TIMEOUT_MS = 40_000
 type AgentProviderId = string
 
+interface ExtensionToolInfo {
+  extensionId: string
+  extensionName?: string
+  toolName: string
+  label: string
+  description: string
+}
+
 function SectionCard({
   title,
   description,
@@ -223,6 +231,7 @@ export function AgentSheet() {
   const [toolAccessMode, setToolAccessMode] = useState<'universal' | 'scoped'>('scoped')
   const [extensions, setExtensions] = useState<string[]>([])
   const [enabledExtensionIds, setEnabledExtensionIds] = useState<Set<string> | null>(null)
+  const [externalTools, setExternalTools] = useState<ExtensionToolInfo[]>([])
   const [skills, setSkills] = useState<string[]>([])
   const [skillIds, setSkillIds] = useState<string[]>([])
   const [mcpServerIds, setMcpServerIds] = useState<string[]>([])
@@ -423,8 +432,11 @@ export function AgentSheet() {
       loadProjects()
       loadClaudeSkills()
       // Fetch enabled extension IDs so we can filter tool toggles
-      api<{ enabledExtensionIds: string[] }>('GET', '/extensions/builtins')
-        .then((res) => { if (res?.enabledExtensionIds) setEnabledExtensionIds(new Set(res.enabledExtensionIds)) })
+      api<{ enabledExtensionIds: string[]; externalTools?: ExtensionToolInfo[] }>('GET', '/extensions/builtins')
+        .then((res) => {
+          if (res?.enabledExtensionIds) setEnabledExtensionIds(new Set(res.enabledExtensionIds))
+          if (Array.isArray(res?.externalTools)) setExternalTools(res.externalTools)
+        })
         .catch(() => {})
       setTestStatus('idle')
       setTestMessage('')
@@ -2642,6 +2654,33 @@ export function AgentSheet() {
         </div>
       )}
 
+      {!hasNativeCapabilities && externalTools.length > 0 && (
+        <div className="mb-8">
+          <label className="block font-display text-[12px] font-600 text-text-2 uppercase tracking-[0.08em] mb-2">Extension Tools</label>
+          <p className="text-[12px] text-text-3/60 mb-3">Attach enabled external extension tools to this agent.</p>
+          <div className="space-y-3">
+            {externalTools.map((t) => {
+              const attached = extensions.includes(t.extensionId)
+              const description = t.extensionName
+                ? `${t.description || 'External extension tool'} (${t.extensionName})`
+                : (t.description || 'External extension tool')
+              return (
+                <label key={`${t.extensionId}:${t.toolName}`} className="flex items-center gap-3 cursor-pointer">
+                  <div
+                    onClick={() => setExtensions((prev) => prev.includes(t.extensionId) ? prev.filter((x) => x !== t.extensionId) : [...prev, t.extensionId])}
+                    className={`w-11 h-6 rounded-full transition-all duration-200 relative shrink-0 ${attached ? 'bg-accent-bright cursor-pointer' : 'bg-white/[0.08] cursor-pointer'}`}
+                  >
+                    <div className={`absolute top-0.5 w-5 h-5 rounded-full bg-white transition-all duration-200 ${attached ? 'left-[22px]' : 'left-0.5'}`} />
+                  </div>
+                  <span className="font-display text-[14px] font-600 text-text-2">{t.label}</span>
+                  <span className="text-[12px] text-text-3">{description}</span>
+                </label>
+              )
+            })}
+          </div>
+        </div>
+      )}
+
       {/* Native capability provider note — not shown for OpenClaw (covered in connection status) */}
       {hasNativeCapabilities && !openclawEnabled && (
         <div className="mb-8 p-4 rounded-[14px] bg-white/[0.02] border border-white/[0.06]">

package/src/components/chat/chat-tool-toggles.tsx

@@ -7,7 +7,7 @@ import { AVAILABLE_TOOLS, PLATFORM_TOOLS } from '@/lib/tool-definitions'
 import type { ToolDefinition } from '@/lib/tool-definitions'
 import type { Session } from '@/types'
 import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '@/components/ui/tooltip'
-import { getEnabledToolIds, getEnabledExtensionIds } from '@/lib/capability-selection'
+import { getEnabledToolIds, getEnabledExtensionIds, isExternalExtensionId } from '@/lib/capability-selection'
 
 interface Props {
   session: Session
@@ -15,6 +15,7 @@ interface Props {
 
 interface ExtensionToolInfo {
   extensionId: string
+  extensionName?: string
   toolName: string
   label: string
   description: string
@@ -55,7 +56,20 @@ export function ChatToolToggles({ session }: Props) {
     return () => document.removeEventListener('mousedown', handler)
   }, [open])
 
-  const toggleTool = async (toolId: string) => {
+  const toggleTool = async (tool: ToolDefinition) => {
+    if (tool.extensionId && isExternalExtensionId(tool.extensionId)) {
+      const updatedExtensions = sessionExtensions.includes(tool.extensionId)
+        ? sessionExtensions.filter((extensionId) => extensionId !== tool.extensionId)
+        : [...sessionExtensions, tool.extensionId]
+      await api('PUT', `/chats/${session.id}`, {
+        tools: sessionTools,
+        extensions: updatedExtensions,
+      })
+      await refreshSession(session.id)
+      return
+    }
+
+    const toolId = tool.id
     const updated = sessionTools.includes(toolId)
       ? sessionTools.filter((t) => t !== toolId)
       : [...sessionTools, toolId]
@@ -78,9 +92,9 @@ export function ChatToolToggles({ session }: Props) {
 
   // Convert external extension tools into ToolDefinition-like items for display
   const extensionToolDefs: ToolDefinition[] = externalTools.map((et) => ({
-    id: et.toolName,
+    id: `${et.extensionId}:${et.toolName}`,
     label: et.label,
-    description: et.description,
+    description: et.extensionName ? `${et.description || 'External extension tool'} (${et.extensionName})` : et.description,
     extensionId: et.extensionId,
   }))
 
@@ -92,7 +106,11 @@ export function ChatToolToggles({ session }: Props) {
 
   const allVisibleTools = groups.flatMap((g) => g.tools)
   const totalCount = allVisibleTools.length
-  const enabledCount = sessionTools.filter((id) => allVisibleTools.some((t) => t.id === id)).length
+  const enabledCount = allVisibleTools.filter((tool) => (
+    tool.extensionId && isExternalExtensionId(tool.extensionId)
+      ? sessionExtensions.includes(tool.extensionId)
+      : sessionTools.includes(tool.id)
+  )).length
 
   return (
     <div className="relative" ref={ref}>
@@ -120,13 +138,17 @@ export function ChatToolToggles({ session }: Props) {
                 <p className="text-[10px] font-600 text-text-3/60 uppercase tracking-wider mb-2">{group.label}</p>
                 {group.tools.map((tool) => {
                   const extDisabled = !isExtensionEnabled(tool)
-                  const enabled = !extDisabled && sessionTools.includes(tool.id)
+                  const enabled = !extDisabled && (
+                    tool.extensionId && isExternalExtensionId(tool.extensionId)
+                      ? sessionExtensions.includes(tool.extensionId)
+                      : sessionTools.includes(tool.id)
+                  )
                   return (
                     <Tooltip key={tool.id}>
                       <TooltipTrigger asChild>
                         <label className={`flex items-center gap-2.5 py-1.5 ${extDisabled ? 'cursor-not-allowed opacity-40' : 'cursor-pointer'}`}>
                           <div
-                            onClick={() => !extDisabled && toggleTool(tool.id)}
+                            onClick={() => !extDisabled && toggleTool(tool)}
                             className={`w-8 h-[18px] rounded-full transition-all duration-200 relative shrink-0
                               ${extDisabled ? 'bg-white/[0.04] cursor-not-allowed' : enabled ? 'bg-accent-bright cursor-pointer' : 'bg-white/[0.12] cursor-pointer'}`}
                           >

package/src/lib/server/connectors/connector-lifecycle.ts

@@ -164,11 +164,23 @@ async function _startConnectorImpl(connectorId: string): Promise<void> {
 
     // Resolve bot token from credential
     let botToken = ''
+    let credentialDecryptError: string | null = null
     if (connector.credentialId) {
       const creds = loadCredentials()
       const cred = creds[connector.credentialId]
       if (cred?.encryptedKey) {
-        try { botToken = decryptKey(cred.encryptedKey) } catch { /* ignore */ }
+        try {
+          botToken = decryptKey(cred.encryptedKey)
+        } catch (err: unknown) {
+          credentialDecryptError = `Failed to decrypt credential "${connector.credentialId}". CREDENTIAL_SECRET may have changed since this credential was stored; restore the previous credential secret or re-add the key.`
+          log.warn(TAG, credentialDecryptError, {
+            connectorId,
+            connectorName: connector.name,
+            platform: connector.platform,
+            credentialId: connector.credentialId,
+            error: errorMessage(err),
+          })
+        }
       }
     }
     // Also check config for inline token (some platforms)
@@ -182,6 +194,10 @@ async function _startConnectorImpl(connectorId: string): Promise<void> {
       botToken = swarmdockFallbackPrivateKey
     }
 
+    if (!botToken && credentialDecryptError) {
+      throw new Error(credentialDecryptError)
+    }
+
     if (!botToken && connector.platform !== 'whatsapp' && connector.platform !== 'openclaw' && connector.platform !== 'signal' && connector.platform !== 'email' && connector.platform !== 'filequeue' && connector.platform !== 'swarmdock') {
       throw new Error('No bot token configured')
     }

package/src/lib/server/session-tools/discovery-approvals.test.ts

@@ -85,6 +85,55 @@ describe('discovery tool access flows', () => {
     assert.equal(output.extensions.includes('shell'), false)
   })
 
+  it('request_tool_access grants external extensions into the session extensions field', () => {
+    const output = runWithTempDataDir(`
+      const storageMod = await import('./src/lib/server/storage')
+      const toolsMod = await import('./src/lib/server/session-tools/index')
+      const storage = storageMod.default || storageMod
+      const toolsApi = toolsMod.default || toolsMod
+
+      const now = Date.now()
+      storage.saveSessions({
+        session_external_extension: {
+          id: 'session_external_extension',
+          name: 'External Extension Access Test',
+          cwd: process.env.WORKSPACE_DIR,
+          user: 'tester',
+          provider: 'openai',
+          model: 'gpt-test',
+          claudeSessionId: null,
+          messages: [],
+          createdAt: now,
+          lastActiveAt: now,
+          sessionType: 'human',
+          agentId: 'default',
+          tools: [],
+          extensions: [],
+        },
+      })
+
+      const built = await toolsApi.buildSessionTools(process.env.WORKSPACE_DIR, [], {
+        sessionId: 'session_external_extension',
+        agentId: 'default',
+        delegationEnabled: false,
+        delegationTargetMode: 'all',
+        delegationTargetAgentIds: [],
+      })
+      const tool = built.tools.find((entry) => entry.name === 'request_tool_access')
+      const raw = await tool.invoke({ toolId: 'freedzhost-critic.js', reason: 'Need the installed critic extension.' })
+      const session = storage.loadSessions().session_external_extension
+      console.log(JSON.stringify({
+        raw,
+        tools: session.tools || [],
+        extensions: session.extensions || [],
+      }))
+    `)
+
+    assert.match(String(output.raw), /tool_access_granted|granted immediately/i)
+    assert.equal(output.tools.includes('freedzhost-critic.js'), false)
+    assert.equal(output.extensions.includes('freedzhost-critic.js'), true)
+  })
+
   it('manage_capabilities request_access grants tools immediately without approval state', () => {
     const output = runWithTempDataDir(`
       const storageMod = await import('./src/lib/server/storage')

package/src/lib/server/storage-auth.test.ts

@@ -3,7 +3,9 @@ import { describe, it, beforeEach, afterEach } from 'node:test'
 import fs from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
+import crypto from 'node:crypto'
 import { spawnSync } from 'node:child_process'
+import Database from 'better-sqlite3'
 
 const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../..')
 
@@ -12,13 +14,26 @@ function runStorageAuthImport(options: {
   generatedEnv?: string
   credentialSecretFile?: string
   externalCredentialSecret?: string
+  swarmclawHome?: boolean
+  buildEnvFiles?: Array<{ relativePath: string; content: string }>
+  encryptedCredentialSecrets?: string[]
 }) {
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'storage-auth-import-'))
-  const dataDir = path.join(tmpDir, 'data')
-  const cwd = path.join(tmpDir, 'cwd')
+  const homeDir = path.join(tmpDir, 'home')
+  const dataDir = options.swarmclawHome ? path.join(homeDir, 'data') : path.join(tmpDir, 'data')
+  const cwd = options.swarmclawHome
+    ? path.join(homeDir, 'builds', 'package-current', '.next', 'standalone')
+    : path.join(tmpDir, 'cwd')
   fs.mkdirSync(dataDir, { recursive: true })
   fs.mkdirSync(cwd, { recursive: true })
   try {
+    for (const [index, entry] of (options.buildEnvFiles ?? []).entries()) {
+      const target = path.join(homeDir, entry.relativePath)
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      fs.writeFileSync(target, entry.content, 'utf8')
+      const time = new Date(Date.now() - (options.buildEnvFiles!.length - index) * 1000)
+      fs.utimesSync(target, time, time)
+    }
     if (options.envLocal !== undefined) {
       fs.writeFileSync(path.join(cwd, '.env.local'), options.envLocal, 'utf8')
     }
@@ -28,12 +43,32 @@ function runStorageAuthImport(options: {
     if (options.credentialSecretFile !== undefined) {
       fs.writeFileSync(path.join(dataDir, 'credential-secret'), options.credentialSecretFile, { encoding: 'utf8', mode: 0o600 })
     }
+    if (options.encryptedCredentialSecrets?.length) {
+      const db = new Database(path.join(dataDir, 'swarmclaw.db'))
+      try {
+        db.exec('CREATE TABLE IF NOT EXISTS credentials (id TEXT PRIMARY KEY, data TEXT NOT NULL)')
+        for (const [index, secret] of options.encryptedCredentialSecrets.entries()) {
+          const id = `cred_${index}`
+          const encryptedKey = encryptForSecret(secret, `token-${index}`)
+          db.prepare('INSERT OR REPLACE INTO credentials (id, data) VALUES (?, ?)').run(id, JSON.stringify({
+            id,
+            provider: 'slack',
+            name: `Credential ${index}`,
+            encryptedKey,
+            createdAt: Date.now(),
+          }))
+        }
+      } finally {
+        db.close()
+      }
+    }
     const env: NodeJS.ProcessEnv = {
       ...process.env,
       DATA_DIR: dataDir,
       WORKSPACE_DIR: path.join(tmpDir, 'workspace'),
       SWARMCLAW_DAEMON_AUTOSTART: '0',
     }
+    if (options.swarmclawHome) env.SWARMCLAW_HOME = homeDir
     delete env.ACCESS_KEY
     delete env.CREDENTIAL_SECRET
     delete env.SWARMCLAW_BUILD_MODE
@@ -69,6 +104,16 @@ function runStorageAuthImport(options: {
   }
 }
 
+function encryptForSecret(secret: string, plaintext: string): string {
+  const key = Buffer.from(secret, 'hex')
+  const iv = crypto.randomBytes(12)
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv)
+  let encrypted = cipher.update(plaintext, 'utf8', 'hex')
+  encrypted += cipher.final('hex')
+  const tag = cipher.getAuthTag().toString('hex')
+  return `${iv.toString('hex')}:${tag}:${encrypted}`
+}
+
 /**
  * Tests for storage-auth helpers.
  *
@@ -249,4 +294,61 @@ describe('credential secret persistence precedence', () => {
     assert.equal(output.credentialSecret, externalSecret)
     assert.equal(output.fileSecret, fileSecret)
   })
+
+  it('recovers the previous npm-global build credential secret before persisting a fresh current cwd secret', () => {
+    const previousSecret = 'd'.repeat(64)
+    const freshCurrentSecret = 'e'.repeat(64)
+    const output = runStorageAuthImport({
+      swarmclawHome: true,
+      envLocal: `CREDENTIAL_SECRET=${freshCurrentSecret}\n`,
+      encryptedCredentialSecrets: [previousSecret],
+      buildEnvFiles: [
+        {
+          relativePath: 'builds/package-1.9.32/.next/standalone/.env.local',
+          content: `CREDENTIAL_SECRET=${previousSecret}\n`,
+        },
+      ],
+    })
+
+    assert.equal(output.credentialSecret, previousSecret)
+    assert.equal(output.fileSecret, previousSecret)
+  })
+
+  it('replaces a non-decrypting DATA_DIR credential secret when a previous build secret decrypts existing credentials', () => {
+    const previousSecret = 'f'.repeat(64)
+    const wrongFileSecret = '1'.repeat(64)
+    const output = runStorageAuthImport({
+      swarmclawHome: true,
+      credentialSecretFile: wrongFileSecret,
+      encryptedCredentialSecrets: [previousSecret],
+      buildEnvFiles: [
+        {
+          relativePath: 'builds/package-1.9.31/.next/standalone/.env.local.bak',
+          content: `CREDENTIAL_SECRET=${previousSecret}\n`,
+        },
+      ],
+    })
+
+    assert.equal(output.credentialSecret, previousSecret)
+    assert.equal(output.fileSecret, previousSecret)
+  })
+
+  it('keeps a DATA_DIR credential secret when it can decrypt existing credentials', () => {
+    const workingFileSecret = '2'.repeat(64)
+    const previousSecret = '3'.repeat(64)
+    const output = runStorageAuthImport({
+      swarmclawHome: true,
+      credentialSecretFile: workingFileSecret,
+      encryptedCredentialSecrets: [workingFileSecret],
+      buildEnvFiles: [
+        {
+          relativePath: 'builds/package-1.9.31/.next/standalone/.env.local',
+          content: `CREDENTIAL_SECRET=${previousSecret}\n`,
+        },
+      ],
+    })
+
+    assert.equal(output.credentialSecret, workingFileSecret)
+    assert.equal(output.fileSecret, workingFileSecret)
+  })
 })

package/src/lib/server/storage-auth.ts

@@ -1,6 +1,7 @@
 import fs from 'fs'
 import path from 'path'
 import crypto from 'crypto'
+import Database from 'better-sqlite3'
 
 import { DATA_DIR, IS_BUILD_BOOTSTRAP } from './data-dir'
 import { log } from '@/lib/server/logger'
@@ -20,6 +21,11 @@ const CREDENTIAL_SECRET_FILE = path.join(DATA_DIR, 'credential-secret')
 
 // --- .env loading ---
 type LoadedEnvFile = Record<string, string>
+type CredentialSecretCandidate = {
+  secret: string
+  source: string
+  mtimeMs: number
+}
 
 function loadEnvFile(filePath: string): LoadedEnvFile {
   const loaded: LoadedEnvFile = {}
@@ -31,6 +37,10 @@ function loadEnvFile(filePath: string): LoadedEnvFile {
   return loaded
 }
 
+function cleanSecret(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
 function applyLoadedEnv(loaded: LoadedEnvFile, externalKeys: Set<string>, options?: { overwriteLoaded?: boolean }) {
   for (const [key, value] of Object.entries(loaded)) {
     if (externalKeys.has(key)) continue
@@ -53,6 +63,161 @@ function loadEnv(): { generated: LoadedEnvFile; local: LoadedEnvFile } {
   applyLoadedEnv(local, externalKeys, { overwriteLoaded: true })
   return { generated, local }
 }
+
+function appendCandidate(candidates: CredentialSecretCandidate[], seen: Set<string>, candidate: CredentialSecretCandidate): void {
+  const secret = cleanSecret(candidate.secret)
+  if (!secret || seen.has(secret)) return
+  seen.add(secret)
+  candidates.push({ ...candidate, secret })
+}
+
+function readEnvCandidate(filePath: string, source: string): CredentialSecretCandidate | null {
+  try {
+    if (!fs.existsSync(filePath)) return null
+    const secret = cleanSecret(loadEnvFile(filePath).CREDENTIAL_SECRET)
+    if (!secret) return null
+    return {
+      secret,
+      source,
+      mtimeMs: fs.statSync(filePath).mtimeMs,
+    }
+  } catch (err) {
+    log.debug(TAG, `Could not inspect legacy CREDENTIAL_SECRET candidate at ${filePath}`, {
+      error: err instanceof Error ? err.message : String(err),
+    })
+    return null
+  }
+}
+
+function findStateHomeCandidates(): string[] {
+  const homes: string[] = []
+  const configuredHome = cleanSecret(process.env.SWARMCLAW_HOME)
+  if (configuredHome) homes.push(path.resolve(configuredHome))
+  if (path.basename(DATA_DIR) === 'data') homes.push(path.dirname(DATA_DIR))
+  return Array.from(new Set(homes))
+}
+
+function collectPreviousBuildSecretCandidates(seen: Set<string>): CredentialSecretCandidate[] {
+  const candidates: CredentialSecretCandidate[] = []
+  for (const home of findStateHomeCandidates()) {
+    const buildsDir = path.join(home, 'builds')
+    let entries: fs.Dirent[]
+    try {
+      entries = fs.readdirSync(buildsDir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !entry.name.startsWith('package-')) continue
+      const buildRoot = path.join(buildsDir, entry.name)
+      const envPaths = [
+        path.join(buildRoot, '.env.local'),
+        path.join(buildRoot, '.env.local.bak'),
+        path.join(buildRoot, '.next', 'standalone', '.env.local'),
+        path.join(buildRoot, '.next', 'standalone', '.env.local.bak'),
+      ]
+      for (const envPath of envPaths) {
+        const candidate = readEnvCandidate(envPath, `previous build env ${envPath}`)
+        if (candidate) appendCandidate(candidates, seen, candidate)
+      }
+    }
+  }
+
+  return candidates.sort((a, b) => b.mtimeMs - a.mtimeMs)
+}
+
+function readEncryptedCredentialKeysFromObject(value: unknown): string[] {
+  if (!value || typeof value !== 'object') return []
+  return Object.values(value as Record<string, unknown>)
+    .map((entry) => {
+      if (!entry || typeof entry !== 'object') return ''
+      return cleanSecret((entry as Record<string, unknown>).encryptedKey)
+    })
+    .filter(Boolean)
+}
+
+function readEncryptedCredentialKeys(): string[] {
+  const keys: string[] = []
+  const jsonPath = path.join(DATA_DIR, 'credentials.json')
+  try {
+    if (fs.existsSync(jsonPath)) {
+      keys.push(...readEncryptedCredentialKeysFromObject(JSON.parse(fs.readFileSync(jsonPath, 'utf8'))))
+    }
+  } catch (err) {
+    log.debug(TAG, `Could not inspect encrypted credentials in ${jsonPath}`, {
+      error: err instanceof Error ? err.message : String(err),
+    })
+  }
+
+  const dbPath = path.join(DATA_DIR, 'swarmclaw.db')
+  try {
+    if (fs.existsSync(dbPath)) {
+      const db = new Database(dbPath, { readonly: true, fileMustExist: true })
+      try {
+        const table = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'credentials'").get()
+        if (table) {
+          const rows = db.prepare('SELECT data FROM credentials LIMIT 500').all() as Array<{ data: string }>
+          const fromDb: Record<string, unknown> = {}
+          for (const [index, row] of rows.entries()) {
+            try {
+              fromDb[`row_${index}`] = JSON.parse(row.data)
+            } catch {
+              // Ignore malformed rows; storage normalization handles them later.
+            }
+          }
+          keys.push(...readEncryptedCredentialKeysFromObject(fromDb))
+        }
+      } finally {
+        db.close()
+      }
+    }
+  } catch (err) {
+    log.debug(TAG, `Could not inspect encrypted credentials in ${dbPath}`, {
+      error: err instanceof Error ? err.message : String(err),
+    })
+  }
+
+  return Array.from(new Set(keys))
+}
+
+function canDecryptCredential(encryptedKey: string, secret: string): boolean {
+  try {
+    const parts = encryptedKey.split(':')
+    if (parts.length !== 3) return false
+    const [ivHex, tagHex, encrypted] = parts
+    const key = Buffer.from(secret, 'hex')
+    if (key.length !== 32) return false
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(ivHex, 'hex'))
+    decipher.setAuthTag(Buffer.from(tagHex, 'hex'))
+    decipher.update(encrypted, 'hex', 'utf8')
+    decipher.final('utf8')
+    return true
+  } catch {
+    return false
+  }
+}
+
+function countDecryptableCredentials(secret: string, encryptedKeys: string[]): number {
+  if (encryptedKeys.length === 0) return 0
+  return encryptedKeys.filter((encryptedKey) => canDecryptCredential(encryptedKey, secret)).length
+}
+
+function selectCredentialSecretCandidate(
+  candidates: CredentialSecretCandidate[],
+  encryptedKeys: string[],
+): CredentialSecretCandidate | null {
+  if (candidates.length === 0) return null
+  if (encryptedKeys.length === 0) return candidates[0]
+
+  let best: { candidate: CredentialSecretCandidate; count: number } | null = null
+  for (const candidate of candidates) {
+    const count = countDecryptableCredentials(candidate.secret, encryptedKeys)
+    if (count === 0) continue
+    if (!best || count > best.count) best = { candidate, count }
+  }
+  return best?.candidate ?? null
+}
 const externalCredentialSecret = process.env.CREDENTIAL_SECRET?.trim() || ''
 const loadedEnv: { generated: LoadedEnvFile; local: LoadedEnvFile } = !IS_BUILD_BOOTSTRAP
   ? loadEnv()
@@ -118,16 +283,31 @@ function writeCredentialSecretFile(secret: string): boolean {
 // Resolve CREDENTIAL_SECRET in this precedence order:
 //   1. process.env (already set externally, e.g. by orchestrator)
 //   2. DATA_DIR/credential-secret (the stable home — survives upgrades)
-//   3. .env files (legacy — values loaded into process.env by loadEnv() above)
+//   3. .env files (legacy current cwd plus prior npm-global build env files)
 //   4. Generate new secret + persist to DATA_DIR/credential-secret
 //
 // Step 2 is the key change: previously the secret only lived in a per-version
 // .env.local (cwd changes on npm-global upgrade), so each upgrade
-// silently regenerated it and orphaned every encrypted credential.
+// silently regenerated it and orphaned every encrypted credential. When
+// encrypted credentials already exist, validate candidate legacy secrets by
+// actually decrypting a stored credential before persisting the migration.
 if (!IS_BUILD_BOOTSTRAP) {
-  const legacyEnvSecret = loadedEnv.local.CREDENTIAL_SECRET?.trim()
-    || loadedEnv.generated.CREDENTIAL_SECRET?.trim()
-    || ''
+  const encryptedCredentialKeys = readEncryptedCredentialKeys()
+  const candidateSeen = new Set<string>()
+  const legacyCandidates: CredentialSecretCandidate[] = []
+  appendCandidate(legacyCandidates, candidateSeen, {
+    secret: cleanSecret(loadedEnv.local.CREDENTIAL_SECRET),
+    source: `${path.join(process.cwd(), '.env.local')}`,
+    mtimeMs: 0,
+  })
+  appendCandidate(legacyCandidates, candidateSeen, {
+    secret: cleanSecret(loadedEnv.generated.CREDENTIAL_SECRET),
+    source: GENERATED_ENV_PATH,
+    mtimeMs: 0,
+  })
+  legacyCandidates.push(...collectPreviousBuildSecretCandidates(candidateSeen))
+
+  const legacyEnvSecret = legacyCandidates[0]?.secret || ''
   const fileSecret = readCredentialSecretFile()
   if (externalCredentialSecret) {
     process.env.CREDENTIAL_SECRET = externalCredentialSecret
@@ -135,23 +315,48 @@ if (!IS_BUILD_BOOTSTRAP) {
       log.warn(TAG, `CREDENTIAL_SECRET is set by the environment and differs from ${CREDENTIAL_SECRET_FILE}; using the environment value.`)
     }
   } else if (fileSecret) {
-    process.env.CREDENTIAL_SECRET = fileSecret
-    if (legacyEnvSecret && legacyEnvSecret !== fileSecret) {
-      // Both persisted locations exist and disagree. Trust DATA_DIR because it
-      // survives npm-global upgrades and Docker restarts.
-      log.warn(TAG, `CREDENTIAL_SECRET mismatch between legacy env files and ${CREDENTIAL_SECRET_FILE}; using the file value.`)
-    }
-  } else if (legacyEnvSecret) {
-    process.env.CREDENTIAL_SECRET = legacyEnvSecret
-    if (writeCredentialSecretFile(legacyEnvSecret)) {
-      log.info(TAG, `Migrated CREDENTIAL_SECRET from .env to ${CREDENTIAL_SECRET_FILE}`)
+    const fileDecryptsCredentials = encryptedCredentialKeys.length === 0
+      || countDecryptableCredentials(fileSecret, encryptedCredentialKeys) > 0
+    if (!fileDecryptsCredentials) {
+      const recovered = selectCredentialSecretCandidate(
+        legacyCandidates.filter((candidate) => candidate.secret !== fileSecret),
+        encryptedCredentialKeys,
+      )
+      if (recovered) {
+        process.env.CREDENTIAL_SECRET = recovered.secret
+        writeCredentialSecretFile(recovered.secret)
+        log.warn(TAG, `Recovered CREDENTIAL_SECRET from ${recovered.source} because ${CREDENTIAL_SECRET_FILE} could not decrypt existing credentials.`)
+      } else {
+        process.env.CREDENTIAL_SECRET = fileSecret
+        log.warn(TAG, `${CREDENTIAL_SECRET_FILE} could not decrypt existing credentials, and no recoverable previous-build CREDENTIAL_SECRET was found.`)
+      }
+    } else {
+      process.env.CREDENTIAL_SECRET = fileSecret
+      if (legacyEnvSecret && legacyEnvSecret !== fileSecret) {
+        // Both persisted locations exist and disagree. Trust DATA_DIR because it
+        // survives npm-global upgrades and Docker restarts.
+        log.warn(TAG, `CREDENTIAL_SECRET mismatch between legacy env files and ${CREDENTIAL_SECRET_FILE}; using the file value.`)
+      }
     }
   } else {
-    // First-ever launch on this DATA_DIR. Generate.
-    const secret = crypto.randomBytes(32).toString('hex')
-    process.env.CREDENTIAL_SECRET = secret
-    writeCredentialSecretFile(secret)
-    log.info(TAG, `Generated CREDENTIAL_SECRET and persisted to ${CREDENTIAL_SECRET_FILE}`)
+    const recovered = selectCredentialSecretCandidate(legacyCandidates, encryptedCredentialKeys)
+    if (recovered) {
+      process.env.CREDENTIAL_SECRET = recovered.secret
+      if (writeCredentialSecretFile(recovered.secret)) {
+        log.info(TAG, `Migrated CREDENTIAL_SECRET from ${recovered.source} to ${CREDENTIAL_SECRET_FILE}`)
+      }
+    } else if (legacyEnvSecret) {
+      process.env.CREDENTIAL_SECRET = legacyEnvSecret
+      if (writeCredentialSecretFile(legacyEnvSecret)) {
+        log.info(TAG, `Migrated CREDENTIAL_SECRET from .env to ${CREDENTIAL_SECRET_FILE}`)
+      }
+    } else {
+      // First-ever launch on this DATA_DIR. Generate.
+      const secret = crypto.randomBytes(32).toString('hex')
+      process.env.CREDENTIAL_SECRET = secret
+      writeCredentialSecretFile(secret)
+      log.info(TAG, `Generated CREDENTIAL_SECRET and persisted to ${CREDENTIAL_SECRET_FILE}`)
+    }
   }
 }
 

package/src/lib/server/universal-tool-access.test.ts

@@ -24,6 +24,16 @@ function scoped(declared: string[] | null | undefined, universe: Set<string> = U
   return Array.from(new Set([...SCOPED_TOOL_BASELINE, ...picks]))
 }
 
+function scopedWithAttachedExtensions(
+  declared: string[] | null | undefined,
+  extraExtensions: string[] | null | undefined,
+  universe: Set<string> = UNIVERSAL_SAMPLE,
+): string[] {
+  const picks = normalize(declared).filter((t) => universe.has(t))
+  const attachedExternalExtensions = normalize(extraExtensions).filter((entry) => /\.(?:m?js)$/i.test(entry))
+  return Array.from(new Set([...SCOPED_TOOL_BASELINE, ...picks, ...attachedExternalExtensions]))
+}
+
 describe('scoped tool access algorithm', () => {
   it('intersects declared tools with the universe and keeps the baseline', () => {
     const out = scoped(['shell', 'files', 'edit_file', 'web'])
@@ -68,4 +78,10 @@ describe('scoped tool access algorithm', () => {
     assert.ok(out.includes('shell'))
     assert.ok(out.includes('files'))
   })
+
+  it('keeps explicitly attached external extensions in scoped mode', () => {
+    const out = scopedWithAttachedExtensions(['shell'], ['freedzhost-critic.js'])
+    assert.ok(out.includes('shell'))
+    assert.ok(out.includes('freedzhost-critic.js'))
+  })
 })

package/src/lib/server/universal-tool-access.ts

@@ -1,4 +1,5 @@
 import { dedup } from '@/lib/shared-utils'
+import { isExternalExtensionId } from '@/lib/capability-selection'
 import { getExtensionManager } from './extensions'
 
 const UNIVERSAL_CORE_EXTENSION_IDS = [
@@ -78,5 +79,6 @@ export function listScopedToolAccessExtensionIds(
   const universe = new Set(listUniversalToolAccessExtensionIds(extraExtensions))
   const declared = normalizeExtensionList(declaredTools)
   const scoped = declared.filter((tool) => universe.has(tool))
-  return dedup([...SCOPED_TOOL_BASELINE, ...scoped])
+  const explicitlyAttachedExternalExtensions = normalizeExtensionList(extraExtensions).filter(isExternalExtensionId)
+  return dedup([...SCOPED_TOOL_BASELINE, ...scoped, ...explicitlyAttachedExternalExtensions])
 }