@shawnstack/quickforge 1.3.30 → 1.4.1

package/server/context-usage.mjs

@@ -0,0 +1,108 @@
+import {
+  estimateContextTokens,
+  estimateTokens,
+  shouldCompact,
+} from '@earendil-works/pi-agent-core'
+
+function safeJson(value) {
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return ''
+  }
+}
+
+function normalizeMessageForTokenEstimate(message) {
+  if (!message || typeof message !== 'object') return message
+  if (message.role !== 'user-with-attachments') return message
+
+  const content = typeof message.content === 'string'
+    ? [{ type: 'text', text: message.content }]
+    : Array.isArray(message.content)
+      ? [...message.content]
+      : []
+
+  if (Array.isArray(message.attachments)) {
+    for (const attachment of message.attachments) {
+      if (attachment?.type === 'image' && attachment.content) {
+        content.push({ type: 'image', data: attachment.content, mimeType: attachment.mimeType })
+      } else if (attachment?.type === 'document' && attachment.extractedText) {
+        content.push({ type: 'text', text: `\n\n[Document: ${attachment.fileName || 'Untitled'}]\n${attachment.extractedText}` })
+      }
+    }
+  }
+
+  return { ...message, role: 'user', content }
+}
+
+function normalizeMessagesForTokenEstimate(messages) {
+  return (Array.isArray(messages) ? messages : []).map(normalizeMessageForTokenEstimate)
+}
+
+function textTokens(text) {
+  if (!text) return 0
+  return estimateTokens({ role: 'user', content: String(text), timestamp: 0 })
+}
+
+function localMessagesTokens(messages) {
+  return normalizeMessagesForTokenEstimate(messages).reduce((total, message) => total + estimateTokens(message), 0)
+}
+
+export function estimateContextUsage({ systemPrompt, messages, tools, model }) {
+  const contextWindow = Number(model?.contextWindow) || 0
+  const reservedOutputTokens = Math.max(0, Number(model?.maxTokens) || 4096)
+  const normalizedMessages = normalizeMessagesForTokenEstimate(messages)
+  const coreEstimate = estimateContextTokens(normalizedMessages)
+  const systemPromptTokens = textTokens(systemPrompt)
+  const toolsTokens = textTokens(safeJson(tools))
+  const messagesTokens = localMessagesTokens(normalizedMessages)
+  const estimatedInputTokens = systemPromptTokens + messagesTokens + toolsTokens
+  const providerBasedContextTokens = Math.max(0, Number(coreEstimate.usageTokens) || 0) > 0
+    ? Math.max(0, Number(coreEstimate.tokens) || 0)
+    : 0
+  const inputTokens = providerBasedContextTokens > 0
+    ? Math.max(estimatedInputTokens, providerBasedContextTokens)
+    : estimatedInputTokens
+  const totalTokens = inputTokens + reservedOutputTokens
+  const percent = contextWindow > 0 ? Math.round((totalTokens / contextWindow) * 1000) / 10 : 0
+  const inputTokenSource = providerBasedContextTokens > 0
+    ? providerBasedContextTokens >= estimatedInputTokens ? 'provider' : 'mixed'
+    : 'estimated'
+
+  return {
+    inputTokens,
+    estimatedInputTokens,
+    knownInputTokens: providerBasedContextTokens,
+    providerContextTokens: providerBasedContextTokens,
+    inputTokenSource,
+    reservedOutputTokens,
+    totalTokens,
+    contextWindow,
+    percent,
+    breakdown: {
+      systemPromptTokens,
+      messagesTokens,
+      toolsTokens,
+      reservedOutputTokens,
+      providerUsageTokens: Math.max(0, Number(coreEstimate.usageTokens) || 0),
+      trailingTokens: Math.max(0, Number(coreEstimate.trailingTokens) || 0),
+      lastUsageIndex: coreEstimate.lastUsageIndex,
+      localEstimatedContextTokens: estimatedInputTokens,
+    },
+  }
+}
+
+export function shouldCompactContextByPercent(usage, thresholdPercent) {
+  const contextWindow = Number(usage?.contextWindow) || 0
+  const totalTokens = Math.max(0, Number(usage?.totalTokens) || 0)
+  const threshold = Math.min(100, Math.max(0, Number(thresholdPercent) || 0))
+  if (!contextWindow) return false
+
+  const thresholdTokens = Math.ceil(contextWindow * threshold / 100)
+  const reserveTokens = Math.min(contextWindow, Math.max(0, contextWindow - thresholdTokens + 1))
+  return shouldCompact(totalTokens, contextWindow, {
+    enabled: true,
+    reserveTokens,
+    keepRecentTokens: 0,
+  })
+}

package/server/custom-commands.mjs

@@ -1,11 +1,59 @@
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import { getEnabledPluginCommandSources } from './plugins/registry.mjs'
+import { userCommandsDir } from './storage.mjs'
 
 const commandsRelativeDirs = ['.claude/commands', '.opencode/commands', '.ai/commands']
 const commandsRelativeDir = '.ai/commands'
 const commandNamePattern = /^(?!.*--)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
 
+/**
+ * Centralized metadata for all built-in slash commands.
+ * This is the single source of truth used by /help output.
+ * Front-end i18n descriptions (i18n.ts) should be kept in sync with the
+ * `description` values here.
+ */
+const builtinCommandCatalog = [
+  {
+    name: 'plan',
+    description: 'Create a plan first; this turn cannot edit files or run commands.',
+    argumentHint: '[task]',
+    permissionNote: 'read-only',
+  },
+  {
+    name: 'review',
+    description: 'Review pending code changes before commit; this turn cannot edit files.',
+    argumentHint: '[scope]',
+    permissionNote: 'no edits',
+  },
+  {
+    name: 'compact',
+    description: 'Create a new chat with this conversation compacted to reduce context usage.',
+    argumentHint: '',
+  },
+  {
+    name: 'clear',
+    description: 'Clear the current chat history and context without calling the model.',
+    argumentHint: '',
+  },
+  {
+    name: 'commands',
+    description: 'List custom commands (project, user-level, and plugin).',
+    argumentHint: '',
+  },
+  {
+    name: 'command new',
+    description: 'Create a project custom command template.',
+    argumentHint: '<name>',
+  },
+  {
+    name: 'help',
+    aliases: ['?'],
+    description: 'Show available commands and their usage.',
+    argumentHint: '',
+  },
+]
+
 function normalizeCommandName(value) {
   const name = String(value || '').trim().toLowerCase()
   return commandNamePattern.test(name) ? name : null
@@ -103,7 +151,7 @@ function firstOptionalBoolean(...values) {
   return undefined
 }
 
-function commandFromFile(file, text, options = {}) {
+export function commandFromFile(file, text, options = {}) {
   const parsed = parseFrontmatter(text)
   if (!parsed.body) return null
 
@@ -229,13 +277,27 @@ async function listPluginCommands(workspaceRoot) {
   return commands
 }
 
+async function listUserCommands() {
+  return listCommandsFromDirectory(userCommandsDir, {
+    source: 'user',
+    relativeRoot: '~/.quickforge/commands',
+  })
+}
+
 export async function listProjectCommands(workspaceRoot, commandDir) {
   const byName = new Map()
 
+  // 1. Plugin commands (lowest priority)
   for (const command of (await listPluginCommands(workspaceRoot)).sort((a, b) => a.name.localeCompare(b.name))) {
     byName.set(command.name, command)
   }
 
+  // 2. User-level commands (~/.quickforge/commands/) — override plugins, overridden by project
+  for (const command of (await listUserCommands()).sort((a, b) => a.name.localeCompare(b.name))) {
+    byName.set(command.name, command)
+  }
+
+  // 3. Project directories: .claude → .opencode → .ai → configured (highest priority)
   for (const dir of commandDirectories(workspaceRoot, commandDir)) {
     const commands = await listCommandsFromDirectory(dir)
     for (const command of commands.sort((a, b) => a.name.localeCompare(b.name))) {
@@ -297,6 +359,7 @@ function escapeXml(value) {
 
 export function parseInternalCommandInvocation(message) {
   const text = textFromUserMessage(message).trim()
+  if (/^\/(?:help|\?)(?:\s+.*)?$/i.test(text)) return { type: 'help' }
   if (/^\/commands(?:\s+.*)?$/i.test(text)) return { type: 'list' }
   if (/^\/clear\s*$/i.test(text)) return { type: 'clear' }
   if (/^\/clear(?:\s+[\s\S]+)$/i.test(text)) return { type: 'invalid-clear-args' }
@@ -344,14 +407,19 @@ export async function handleInternalCommand(invocation, workspaceRoot, commandDi
     return 'Usage: /clear'
   }
 
-  if (!workspaceRoot) {
-    return 'Custom commands require an active project chat.'
+  if (invocation.type === 'help') {
+    return formatHelpText(await listProjectCommands(workspaceRoot, commandDir))
   }
 
+  // /commands and /help work without a project (user-level commands are global)
   if (invocation.type === 'list') {
     return formatCommandList(await listProjectCommands(workspaceRoot, commandDir))
   }
 
+  if (!workspaceRoot) {
+    return 'Custom commands require an active project chat.'
+  }
+
   if (invocation.type === 'new') {
     return createCommandTemplate(workspaceRoot, invocation.name)
   }
@@ -367,17 +435,17 @@ function formatPermission(value) {
   return value === false ? 'false' : 'true'
 }
 
-function formatCommandList(commands) {
+export function formatCommandList(commands) {
   if (commands.length === 0) {
     return [
-      'No project custom commands found.',
+      'No custom commands found.',
       '',
       'Create one with:',
       '```text',
       '/command new review',
       '```',
       '',
-      'Or add Markdown files under `.claude/commands/`, `.opencode/commands/`, or `.ai/commands/`, for example `.ai/commands/review.md`.',
+      'Or add Markdown files under `~/.quickforge/commands/` (user-level), or `.claude/commands/`, `.opencode/commands/`, `.ai/commands/` (project-level), for example `.ai/commands/review.md`.',
     ].join('\n')
   }
 
@@ -389,37 +457,59 @@ function formatCommandList(commands) {
   })
 
   return [
-    'Project custom commands:',
+    'Custom commands:',
     '',
     ...rows,
     '',
-    'Command files live in `.claude/commands/*.md`, `.opencode/commands/*.md`, `.ai/commands/*.md`, or configured directories. Use `$ARGUMENTS` inside a command file to insert invocation arguments.',
+    'Command files live in `~/.quickforge/commands/*.md` (user-level), `.claude/commands/*.md`, `.opencode/commands/*.md`, `.ai/commands/*.md`, or configured directories. Use `$ARGUMENTS` inside a command file to insert invocation arguments.',
   ].join('\n')
 }
 
-async function createCommandTemplate(workspaceRoot, name) {
-  const commandName = normalizeCommandName(name)
-  if (!commandName) {
-    return `Invalid command name: ${name}\n\nUse lowercase letters, numbers, and hyphens.`
-  }
+function formatBuiltinCommandRows() {
+  return builtinCommandCatalog.map((cmd) => {
+    const hint = cmd.argumentHint ? ` ${cmd.argumentHint}` : ''
+    const aliases = cmd.aliases?.length
+      ? ` (alias: ${cmd.aliases.map((alias) => `/${alias}`).join(', ')})`
+      : ''
+    const perm = cmd.permissionNote ? ` \[${cmd.permissionNote}\]` : ''
+    return `- \`/${cmd.name}${hint}\`${aliases} — ${cmd.description}${perm}`
+  })
+}
 
-  const dir = commandDirectory(workspaceRoot)
-  const file = path.join(dir, `${commandName}.md`)
-  try {
-    await fs.mkdir(dir, { recursive: true })
-    await fs.writeFile(file, commandTemplate(commandName), { encoding: 'utf8', flag: 'wx' })
-  } catch (error) {
-    if (error?.code === 'EEXIST') {
-      return `Custom command already exists: ${commandsRelativeDir}/${commandName}.md`
-    }
-    throw error
+export function formatHelpText(customCommands = []) {
+  const sections = [
+    'QuickForge command reference',
+    '',
+    'Built-in commands:',
+    '',
+    ...formatBuiltinCommandRows(),
+  ]
+
+  if (customCommands.length > 0) {
+    sections.push('', formatCommandList(customCommands))
+  } else {
+    sections.push(
+      '',
+      'No custom commands found. Add Markdown files under `~/.quickforge/commands/` (user-level) or `.claude/commands/`, `.opencode/commands/`, `.ai/commands/` (project-level).',
+    )
   }
 
-  return [
-    `Created custom command: ${commandsRelativeDir}/${commandName}.md`,
-    '',
-    `Run it with: /${commandName} your arguments`,
-  ].join('\n')
+  return sections.join('\n')
+}
+
+async function createCommandTemplate(workspaceRoot, name) {
+  const result = await createCommandFile(workspaceRoot, name)
+  if (result.ok) {
+    return [
+      `Created custom command: ${result.relativePath}`,
+      '',
+      `Run it with: /${result.name} your arguments`,
+    ].join('\n')
+  }
+  if (result.reason === 'exists') {
+    return `Custom command already exists: ${commandsRelativeDir}/${result.name}.md`
+  }
+  return `Invalid command name: ${name}\n\nUse lowercase letters, numbers, and hyphens.`
 }
 
 function commandTemplate(name) {
@@ -436,3 +526,30 @@ allow_commands: false
 $ARGUMENTS
 `
 }
+
+export async function createCommandFile(workspaceRoot, name) {
+  const commandName = normalizeCommandName(name)
+  if (!commandName) {
+    return { ok: false, reason: 'invalid' }
+  }
+  const dir = commandDirectory(workspaceRoot)
+  if (!dir) {
+    return { ok: false, reason: 'no-project' }
+  }
+  const file = path.join(dir, `${commandName}.md`)
+  try {
+    await fs.mkdir(dir, { recursive: true })
+    await fs.writeFile(file, commandTemplate(commandName), { encoding: 'utf8', flag: 'wx' })
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      return { ok: false, reason: 'exists', name: commandName, filePath: file }
+    }
+    throw error
+  }
+  return {
+    ok: true,
+    name: commandName,
+    filePath: file,
+    relativePath: `${commandsRelativeDir}/${commandName}.md`,
+  }
+}

package/server/index.mjs

@@ -537,6 +537,19 @@ await initializeActiveProject()
 setActiveWorkspaceRootForFilesystem(getWorkspaceRoot())
 startScheduledTaskRunner()
 
+server.on('error', (error) => {
+  // Handle listen errors (most commonly EADDRINUSE). Without this, Node would
+  // throw an uncaught exception and crash with only a raw stack trace in the log.
+  if (error.code === 'EADDRINUSE') {
+    logger.error(`Port ${port} is already in use. QuickForge could not start.`)
+    logger.error('Hint: stop the running instance with "quickforge stop" or "quickforge restart", or use a different port with QUICKFORGE_PORT=<port>.')
+  } else {
+    logger.error(`QuickForge failed to listen on ${host}:${port}: ${error.message}`)
+  }
+  flushLogger()
+  process.exit(1)
+})
+
 server.listen(port, host, () => {
   logger.info(`QuickForge local API: http://${host}:${port}`)
   if (shareLanEnabled) {

package/server/mcp/registry.mjs

@@ -231,6 +231,46 @@ export async function refreshMcpConnections() {
   return refreshPromise
 }
 
+export async function reconnectMcpServer(name) {
+  const normalizedName = String(name || '').trim()
+  // close any existing connection first (bypasses retry backoff)
+  const existing = connections.get(normalizedName)
+  if (existing) {
+    connections.delete(normalizedName)
+    await closeConnection(existing)
+  }
+  const servers = await readMcpServers()
+  const config = servers.find((server) => server.name === normalizedName)
+  if (!config) {
+    const error = new Error(`MCP server not found: ${normalizedName}`)
+    error.statusCode = 404
+    throw error
+  }
+  if (!config.enabled) {
+    const error = new Error(`MCP server is disabled: ${normalizedName}`)
+    error.statusCode = 400
+    throw error
+  }
+  try {
+    const connection = await connectServer(config)
+    connections.set(config.name, connection)
+  } catch (error) {
+    logger.error(`Failed to reconnect MCP server ${config.name}:`, error)
+    connections.set(config.name, {
+      config,
+      client: null,
+      transport: null,
+      status: 'error',
+      error: error?.message || 'Failed to connect MCP server',
+      tools: [],
+      connectedAt: null,
+      stderr: '',
+      lastAttemptAt: Date.now(),
+    })
+  }
+  return connections
+}
+
 export async function getMcpStatus() {
   await refreshMcpConnections()
   const servers = await readMcpServers()

package/server/routes/agent.mjs

@@ -6,6 +6,7 @@ import {
   steerAgent,
   followUpAgent,
   getSessionState,
+  getSessionStatus,
   getSessionEventBus,
   tryAcquireSse,
   releaseSse,
@@ -82,7 +83,7 @@ export async function handleAgentApi(req, res, url) {
       error.statusCode = 400
       throw error
     }
-    const result = await runPrompt(sessionId, message, body?.selectedCapabilities)
+    const result = await runPrompt(sessionId, message, body?.selectedCapabilities, body?.command)
     sendJson(res, 200, result)
     return
   }
@@ -112,6 +113,24 @@ export async function handleAgentApi(req, res, url) {
     return
   }
 
+  // GET /api/agents/:sessionId/status - get lightweight session status
+  if (req.method === 'GET' && subPath === 'status') {
+    let status = getSessionStatus(sessionId)
+    if (!status) {
+      // Try to restore from persistent storage before giving up.
+      // This recovers sessions that were evicted by idle timeout.
+      await restoreAgent(sessionId)
+      status = getSessionStatus(sessionId)
+    }
+    if (!status) {
+      const error = new Error('Session not found')
+      error.statusCode = 404
+      throw error
+    }
+    sendJson(res, 200, status)
+    return
+  }
+
   // POST /api/agents/:sessionId — create/ensure agent
   if (req.method === 'POST' && parts.length === 3) {
     const body = await readJsonBody(req)

package/server/routes/mcp.mjs

@@ -1,7 +1,7 @@
 import { sendJson, readJsonBody } from '../utils/response.mjs'
 import { refreshAllSessionTools } from '../agent-manager.mjs'
 import { deleteMcpServer, normalizeMcpServers, readMcpServers, setMcpServerEnabled, upsertMcpServer, writeMcpServers } from '../mcp/config.mjs'
-import { getMcpStatus, refreshMcpConnections } from '../mcp/registry.mjs'
+import { getMcpStatus, reconnectMcpServer, refreshMcpConnections } from '../mcp/registry.mjs'
 
 async function refreshMcpAndAgentTools() {
   await refreshMcpConnections()
@@ -54,6 +54,12 @@ export async function handleMcpApi(req, res, url) {
     return
   }
 
+  if (req.method === 'POST' && parts[0] === 'api' && parts[1] === 'mcp' && parts[2] === 'reconnect' && parts[3]) {
+    await reconnectMcpServer(decodeURIComponent(parts[3]))
+    sendJson(res, 200, await refreshMcpAndAgentTools())
+    return
+  }
+
   if (req.method === 'DELETE' && parts[0] === 'api' && parts[1] === 'mcp' && parts[2] === 'servers' && parts[3]) {
     await deleteMcpServer(decodeURIComponent(parts[3]))
     sendJson(res, 200, await refreshMcpAndAgentTools())

package/server/routes/project.mjs

@@ -1,6 +1,6 @@
 import { sendJson, readJsonBody, decodeSegment } from '../utils/response.mjs'
 import { getActiveProject, setActiveProjectPath, readProjectConfig } from '../project-config.mjs'
-import { listProjectCommands } from '../custom-commands.mjs'
+import { listProjectCommands, createCommandFile } from '../custom-commands.mjs'
 import { atomicProjectConfigUpdate } from '../storage.mjs'
 import { getWorkspaceRoot, setWorkspaceRoot } from '../utils/workspace.mjs'
 import { selectDirectoryDialog, openPathInFileManager } from '../utils/platform.mjs'
@@ -20,7 +20,7 @@ export async function handleProjectApi(req, res, url) {
     const project = projectId
       ? config.projects.find((item) => item.id === projectId)
       : getActiveProject(config)
-    const commands = project?.path ? await listProjectCommands(project.path, project.commandDir) : []
+    const commands = await listProjectCommands(project?.path, project?.commandDir)
     sendJson(res, 200, {
       commands: commands.map((command) => ({
         name: command.name,
@@ -29,6 +29,7 @@ export async function handleProjectApi(req, res, url) {
         allowEdit: command.allowEdit,
         allowCommands: command.allowCommands,
         relativePath: command.relativePath,
+        filePath: command.filePath,
         source: command.source,
         pluginName: command.pluginName,
       })),
@@ -107,6 +108,35 @@ export async function handleProjectApi(req, res, url) {
     return
   }
 
+  if (req.method === 'POST' && url.pathname === '/api/project/open-path') {
+    const body = await readJsonBody(req)
+    const active = body?.projectId
+      ? config.projects.find((project) => project.id === body.projectId) ?? getActiveProject(config)
+      : getActiveProject(config)
+    const target = String(body?.path || '')
+    const resolved = target && path.isAbsolute(target)
+      ? path.resolve(target)
+      : path.resolve(active?.path || '', target)
+    await openPathInFileManager(resolved)
+    sendJson(res, 200, { ok: true })
+    return
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/project/command') {
+    const body = await readJsonBody(req)
+    const active = body?.projectId
+      ? config.projects.find((project) => project.id === body.projectId) ?? getActiveProject(config)
+      : getActiveProject(config)
+    if (!active?.path) {
+      const error = new Error('No active project')
+      error.statusCode = 400
+      throw error
+    }
+    const result = await createCommandFile(active.path, body?.name)
+    sendJson(res, 200, result)
+    return
+  }
+
   if (req.method === 'DELETE' && url.pathname.startsWith('/api/project/')) {
     const id = decodeSegment(url.pathname.split('/').filter(Boolean)[2])
     const updated = await atomicProjectConfigUpdate((cfg) => {

package/server/routes/shared-conversation.mjs

@@ -363,7 +363,7 @@ export async function handleSharedConversationApi(req, res, url) {
     assertOperate(record)
     const body = await readJsonBody(req)
     await restoreAgent(record.sessionId)
-    const result = await runPrompt(record.sessionId, messageFromBody(body, record, req))
+    const result = await runPrompt(record.sessionId, messageFromBody(body, record, req), [], body?.command)
     sendJson(res, 200, result)
     return
   }

package/server/storage.mjs

@@ -94,6 +94,7 @@ export const configDir = path.join(dataDir, 'config')
 export const storageDir = path.join(dataDir, 'storage')
 export const cacheDir = path.join(dataDir, 'cache')
 export const logsDir = path.join(dataDir, 'logs')
+export const userCommandsDir = path.join(dataDir, 'commands')
 
 const quickForgeConfigFile = path.join(configDir, 'config.json')
 const configMigrationMarkerFile = path.join(configDir, '.layout-migrated')
@@ -705,26 +706,38 @@ export async function atomicProjectConfigUpdate(updateFn) {
   })
 }
 
-export async function ensureStorage() {
-  await fs.mkdir(configDir, { recursive: true })
-  await fs.mkdir(storageDir, { recursive: true })
-  await fs.mkdir(cacheDir, { recursive: true })
-  await fs.mkdir(logsDir, { recursive: true })
-  await Promise.all([
-    fs.mkdir(path.join(cacheDir, 'global', 'llm'), { recursive: true }),
-    fs.mkdir(path.join(cacheDir, 'global', 'tmp'), { recursive: true }),
-    fs.mkdir(path.join(cacheDir, 'projects'), { recursive: true }),
-    fs.mkdir(path.join(storageDir, 'conversations', 'global', 'sessions'), { recursive: true }),
-    fs.mkdir(path.join(storageDir, 'conversations', 'projects'), { recursive: true }),
-    cleanOldLogs(),
-  ])
-
-  await migrateUnifiedConfig()
+// Cached storage-initialization promise.  ensureStorage() is idempotent (mkdir
+// recursive, one-shot migration gated by a marker file, ensureJsonFile), so once
+// it succeeds we can skip the redundant syscalls (~20 per call) every later call
+// would perform.  Reset on failure so the next call can retry.
+let storageInitPromise = null
 
-  await Promise.all([
-    ensureJsonFile(quickForgeConfigFile, defaultConfig()),
-    ensureJsonFile(sessionStoreFile('sessions-metadata', { scope: 'global' })),
-  ])
+export function ensureStorage() {
+  if (storageInitPromise) return storageInitPromise
+  storageInitPromise = (async () => {
+    await fs.mkdir(configDir, { recursive: true })
+    await fs.mkdir(storageDir, { recursive: true })
+    await fs.mkdir(cacheDir, { recursive: true })
+    await fs.mkdir(logsDir, { recursive: true })
+    await Promise.all([
+      fs.mkdir(path.join(cacheDir, 'global', 'llm'), { recursive: true }),
+      fs.mkdir(path.join(cacheDir, 'global', 'tmp'), { recursive: true }),
+      fs.mkdir(path.join(cacheDir, 'projects'), { recursive: true }),
+      fs.mkdir(path.join(storageDir, 'conversations', 'global', 'sessions'), { recursive: true }),
+      fs.mkdir(path.join(storageDir, 'conversations', 'projects'), { recursive: true }),
+      cleanOldLogs(),
+    ])
+
+    await migrateUnifiedConfig()
+
+    await Promise.all([
+      ensureJsonFile(quickForgeConfigFile, defaultConfig()),
+      ensureJsonFile(sessionStoreFile('sessions-metadata', { scope: 'global' })),
+    ])
+  })()
+  // Reset on failure so the next call can retry instead of caching a rejection.
+  storageInitPromise.catch(() => { storageInitPromise = null })
+  return storageInitPromise
 }
 
 export async function readStore(storeName) {