helloagents 3.0.35 → 3.0.38

package/scripts/project-session-cleanup.mjs

@@ -10,10 +10,10 @@ import {
   writeJsonFileAtomic,
 } from './runtime-scope.mjs'
 import { LONG_RUNNING_TTL_MS } from './runtime-ttl.mjs'
+import { looksLikeAutoCreatedState, readStateDocument } from './state-document.mjs'
 
 export const PROJECT_SESSION_CLEANUP_COOLDOWN_MS = 10 * 60 * 1000
 export const PROJECT_SESSION_MAX_AGE_MS = LONG_RUNNING_TTL_MS
-
 function removePath(filePath, result, bucket) {
   try {
     rmSync(filePath, { recursive: true, force: true })
@@ -23,6 +23,10 @@ function removePath(filePath, result, bucket) {
   }
 }
 
+function isDebugLog(entryName = '') {
+  return /\.log$/i.test(entryName)
+}
+
 function isDirectoryEmptyRecursive(dirPath) {
   const entries = readdirSync(dirPath, { withFileTypes: true })
   if (entries.length === 0) return true
@@ -32,9 +36,10 @@ function isDirectoryEmptyRecursive(dirPath) {
   })
 }
 
-function shouldKeepSession(active, workspace, session) {
+function shouldKeepNestedSession(active, workspace, sessionName) {
   const activeWorkspace = active.workspace || active.branch || ''
-  return activeWorkspace === workspace && active.session === session
+  const activeSession = active.session || ''
+  return activeWorkspace === workspace && activeSession === sessionName
 }
 
 function readCleanupCheckedAt(active) {
@@ -55,6 +60,14 @@ function hasStateSnapshot(sessionDir) {
   return existsSync(join(sessionDir, 'STATE.md'))
 }
 
+function isAutoCreatedSeedSession(sessionDir) {
+  const statePath = join(sessionDir, 'STATE.md')
+  if (!existsSync(statePath)) return false
+
+  const { body } = readStateDocument(statePath)
+  return looksLikeAutoCreatedState(body)
+}
+
 function readSessionStateMtimeMs(sessionDir) {
   try {
     return statSync(join(sessionDir, 'STATE.md')).mtimeMs
@@ -79,6 +92,32 @@ function cleanupTransientSessionTemps(sessionsDir, result) {
   }
 }
 
+function cleanupLegacyProjectArtifacts(activationDir, result) {
+  const artifactsDir = join(activationDir, 'artifacts')
+  if (!existsSync(artifactsDir)) return
+
+  let removableEntries = []
+  try {
+    removableEntries = readdirSync(artifactsDir, { withFileTypes: true })
+  } catch (error) {
+    result.errors.push(`${artifactsDir}: ${error.message}`)
+    return
+  }
+
+  for (const entry of removableEntries) {
+    if (!entry.isFile() || !isDebugLog(entry.name)) continue
+    removePath(join(artifactsDir, entry.name), result, 'removedLegacyArtifacts')
+  }
+
+  try {
+    if (isDirectoryEmptyRecursive(artifactsDir)) {
+      removePath(artifactsDir, result, 'removedLegacyArtifacts')
+    }
+  } catch (error) {
+    result.errors.push(`${artifactsDir}: ${error.message}`)
+  }
+}
+
 export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs = 0, maxAgeMs = PROJECT_SESSION_MAX_AGE_MS } = {}) {
   const projectRoot = getProjectRoot(cwd)
   const activationDir = getProjectActivationDir(projectRoot)
@@ -90,7 +129,9 @@ export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs =
     removedEmptyDirs: [],
     removedInactiveDirs: [],
     removedNoStateDirs: [],
+    removedSeedDirs: [],
     removedTempFiles: [],
+    removedLegacyArtifacts: [],
     errors: [],
     skipped: false,
   }
@@ -109,30 +150,33 @@ export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs =
   } catch (error) {
     result.errors.push(`${sessionsDir}: ${error.message}`)
   }
+  cleanupLegacyProjectArtifacts(activationDir, result)
 
   for (const workspaceEntry of readdirSync(sessionsDir, { withFileTypes: true })) {
     if (!workspaceEntry.isDirectory()) continue
     const workspaceDir = join(sessionsDir, workspaceEntry.name)
-
-    for (const sessionEntry of readdirSync(workspaceDir, { withFileTypes: true })) {
-      if (!sessionEntry.isDirectory()) continue
-      const sessionDir = join(workspaceDir, sessionEntry.name)
-      if (shouldKeepSession(active, workspaceEntry.name, sessionEntry.name)) continue
-
-      try {
+    try {
+      const nestedEntries = readdirSync(workspaceDir, { withFileTypes: true }).filter((entry) => entry.isDirectory())
+      for (const nestedEntry of nestedEntries) {
+        const sessionDir = join(workspaceDir, nestedEntry.name)
+        if (shouldKeepNestedSession(active, workspaceEntry.name, nestedEntry.name)) continue
         if (isDirectoryEmptyRecursive(sessionDir)) {
           removePath(sessionDir, result, 'removedEmptyDirs')
-        } else if (!hasStateSnapshot(sessionDir)) {
+          continue
+        }
+        if (!hasStateSnapshot(sessionDir)) {
           removePath(sessionDir, result, 'removedNoStateDirs')
-        } else if (isStaleStateSession(sessionDir, now, maxAgeMs)) {
+          continue
+        }
+        if (isAutoCreatedSeedSession(sessionDir)) {
+          removePath(sessionDir, result, 'removedSeedDirs')
+          continue
+        }
+        if (isStaleStateSession(sessionDir, now, maxAgeMs)) {
           removePath(sessionDir, result, 'removedInactiveDirs')
         }
-      } catch (error) {
-        result.errors.push(`${sessionDir}: ${error.message}`)
       }
-    }
 
-    try {
       if (isDirectoryEmptyRecursive(workspaceDir)) {
         removePath(workspaceDir, result, 'removedEmptyDirs')
       }

package/scripts/project-storage.mjs

@@ -114,8 +114,8 @@ export function getProjectSessionStateScope(cwd, options = {}) {
   const scope = getProjectSessionScope(cwd, normalizeRuntimeOptions(options))
 
   return {
-    stateScope: 'session',
-    stateSessionToken: scope.session,
+    stateScope: 'workspace-session',
+    stateSessionToken: scope.session || '',
     stateSessionMode: scope.sessionMode,
     stateWorkspace: scope.workspace || scope.branch,
     sessionDir: scope.sessionDir,
@@ -246,9 +246,6 @@ export function buildProjectStorageHint(cwd, options = {}) {
   const summary = getProjectStoreSummary(cwd, options)
   const hints = []
   hints.push(`当前状态文件写入 \`${summary.promptStatePath}\``)
-  if (summary.stateSessionMode === 'default') {
-    hints.push(`当前宿主未提供稳定会话标识，因此使用工作区默认位置 \`${summary.stateSessionToken}\``)
-  }
   if (summary.usesSharedStore) {
     hints.push(`项目存储：\`project_store_mode=repo-shared\`；项目本地存储/会话运行态目录仍是 \`${summary.promptActivationDir}\`，知识库/方案目录改为 \`${summary.promptStoreDir}\``)
   }
@@ -277,9 +274,6 @@ export function buildProjectStorageBlock(cwd, options = {}) {
 
   const explanations = []
   explanations.push('说明：状态文件只使用 `state_path`。')
-  if (summary.stateSessionMode === 'default') {
-    explanations.push('说明：当前宿主未提供稳定会话标识，因此使用工作区默认位置。')
-  }
   if (summary.usesSharedStore) {
     explanations.push('说明：状态文件与会话产物写项目本地存储目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。')
   } else {

package/scripts/runtime-artifacts.mjs

@@ -7,7 +7,7 @@ import {
   readSessionArtifact,
   writeSessionArtifact,
 } from './session-capsule.mjs'
-import { EVIDENCE_MAX_AGE_MS, LONG_RUNNING_TTL_HOURS } from './runtime-ttl.mjs'
+import { EVIDENCE_MAX_AGE_MS, LONG_RUNNING_TTL_HOURS, STANDARD_RUNTIME_TTL_HOURS } from './runtime-ttl.mjs'
 
 export { EVIDENCE_MAX_AGE_MS }
 
@@ -87,7 +87,7 @@ export function validateEvidenceTimestamp(evidence, now, label) {
       required: true,
       status: 'stale-time',
       evidence,
-      details: [`${label}超过 ${LONG_RUNNING_TTL_HOURS} 小时`],
+      details: [`${label}超过 ${STANDARD_RUNTIME_TTL_HOURS} 小时（长任务上限：${LONG_RUNNING_TTL_HOURS} 小时）`],
     }
   }
   return null

package/scripts/runtime-scope.mjs

@@ -4,17 +4,24 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync,
 import { dirname, join, normalize, resolve } from 'node:path'
 import { homedir } from 'node:os'
 
-import { resolveSessionToken } from './session-token.mjs'
+import {
+  resolveProjectSessionAliasToken,
+  resolveProjectSessionToken,
+  resolveSessionToken,
+} from './session-token.mjs'
 import { USER_RUNTIME_MAX_AGE_MS } from './runtime-ttl.mjs'
 import { cleanupUserRuntimeRoot, getUserRuntimeRoot } from './runtime-user-cleanup.mjs'
 import { FULL_CARRIER_PROFILE_MARKER } from './cli-utils.mjs'
+import { readStateDocument, writeStateDocument } from './state-document.mjs'
 
 export const PROJECT_DIR_NAME = '.helloagents'
 export const PROJECT_SESSIONS_DIR_NAME = 'sessions'
 export const PROJECT_ARTIFACTS_DIR_NAME = 'artifacts'
 export const EVENTS_FILE_NAME = 'events.jsonl'
 export const ACTIVE_SESSION_FILE_NAME = 'active.json'
+export const PROJECT_RUNTIME_FILE_NAME = 'runtime.json'
 export const DEFAULT_STATE_SESSION_TOKEN = 'default'
+export const LEGACY_SESSION_POINTERS_FILE_NAME = 'session-pointers.json'
 export const USER_RUNTIME_DIR_NAME = 'runtime'
 export { cleanupUserRuntimeRoot, getUserRuntimeRoot, USER_RUNTIME_MAX_AGE_MS }
 
@@ -260,6 +267,38 @@ function buildInitialStateSnapshot({
   ].join('\n')
 }
 
+function normalizeProjectSessionState(scope) {
+  if (!scope?.statePath) return
+
+  const currentDocument = readStateDocument(scope.statePath)
+  if (currentDocument.hasMetadata) {
+    if (currentDocument.metadata && typeof currentDocument.metadata === 'object' && !existsSync(scope.runtimePath)) {
+      writeJsonFileAtomic(scope.runtimePath, currentDocument.metadata)
+    }
+    writeStateDocument(scope.statePath, {
+      body: currentDocument.body,
+    })
+  }
+
+  const workspaceStatePath = scope.workspaceDir ? join(scope.workspaceDir, 'STATE.md') : ''
+  if (!workspaceStatePath || samePath(workspaceStatePath, scope.statePath) || !existsSync(workspaceStatePath)) return
+
+  const legacyDocument = readStateDocument(workspaceStatePath)
+  if (!existsSync(scope.statePath) && legacyDocument.body.trim()) {
+    writeStateDocument(scope.statePath, {
+      body: legacyDocument.body,
+    })
+  }
+  if (legacyDocument.metadata && typeof legacyDocument.metadata === 'object' && !existsSync(scope.runtimePath)) {
+    writeJsonFileAtomic(scope.runtimePath, legacyDocument.metadata)
+  }
+  if (legacyDocument.hasMetadata) {
+    writeStateDocument(workspaceStatePath, {
+      body: legacyDocument.body,
+    })
+  }
+}
+
 export function ensureProjectLocalRuntime(cwd, options = {}) {
   const normalizedCwd = normalizePath(cwd || process.cwd())
   const localDir = getProjectLocalDir(normalizedCwd)
@@ -271,6 +310,7 @@ export function ensureProjectLocalRuntime(cwd, options = {}) {
   if (!existsSync(scope.statePath)) {
     writeFileSync(scope.statePath, `${buildInitialStateSnapshot(options.stateSeed || {})}\n`, 'utf-8')
   }
+  normalizeProjectSessionState(scope)
 
   return scope
 }
@@ -323,21 +363,18 @@ function findProjectActivationDir(cwd) {
 
 function resolvePayloadSessionToken(payload = {}) {
   if (payload?._helloagentsSessionAlias) return ''
-  return resolveSessionToken({
+  return resolveProjectSessionToken({
     payload,
     env: {},
-    ppid: 0,
-    allowPpidFallback: false,
   })
 }
 
 function resolveEnvSessionToken(env = process.env) {
-  return resolveSessionToken({
-    payload: {},
-    env,
-    ppid: 0,
-    allowPpidFallback: false,
-  })
+  return resolveProjectSessionToken({ payload: {}, env })
+}
+
+function resolveEnvSessionAliasToken(env = process.env) {
+  return resolveProjectSessionAliasToken({ env })
 }
 
 function resolveTransientSessionToken({ payload = {}, env = process.env, ppid = process.ppid } = {}) {
@@ -349,10 +386,24 @@ function resolveTransientSessionToken({ payload = {}, env = process.env, ppid =
   })
 }
 
+function buildScopedSessionToken(kind = '', raw = '') {
+  const normalizedKind = sanitizeRuntimeSegment(kind, 'session')
+  const value = sanitizeRuntimeSegment(String(raw || '').trim(), '')
+  if (!value) return ''
+  return `${normalizedKind}-${value}`
+}
+
 function getActiveSessionPath(activationDir) {
   return join(activationDir, PROJECT_SESSIONS_DIR_NAME, ACTIVE_SESSION_FILE_NAME)
 }
 
+function removeLegacySessionPointersFile(activationDir) {
+  if (!activationDir) return
+  try {
+    rmSync(join(activationDir, PROJECT_SESSIONS_DIR_NAME, LEGACY_SESSION_POINTERS_FILE_NAME), { force: true })
+  } catch {}
+}
+
 function resolveActiveSessionToken({ activationDir, projectRoot, workspace, now = Date.now() } = {}) {
   const active = readJsonFile(getActiveSessionPath(activationDir), null)
   if (!active || typeof active !== 'object') return ''
@@ -384,14 +435,15 @@ function resolveActiveAliasSession({ activationDir, projectRoot, workspace, alia
 }
 
 export function writeActiveProjectSession(scope, { host = '', source = '', env = process.env } = {}) {
-  if (!scope?.active || !scope.activationDir || !scope.session) return ''
+  if (!scope?.active || !scope.activationDir || !scope.workspace) return ''
 
   const activePath = getActiveSessionPath(scope.activationDir)
   const current = readJsonFile(activePath, null) || {}
   const aliases = current.aliases && typeof current.aliases === 'object' ? current.aliases : {}
   const envToken = sanitizeRuntimeSegment(resolveEnvSessionToken(env), '')
   if (envToken && envToken !== scope.session) aliases[envToken] = scope.session
-
+  const aliasToken = sanitizeRuntimeSegment(resolveEnvSessionAliasToken(env), '')
+  if (aliasToken && aliasToken !== scope.session) aliases[aliasToken] = scope.session
   writeJsonFileAtomic(activePath, {
     version: 1,
     cwd: scope.cwd,
@@ -409,9 +461,14 @@ export function writeActiveProjectSession(scope, { host = '', source = '', env =
 
 function chooseProjectSession({ payload, env, activationDir, projectRoot, workspace }) {
   const payloadToken = sanitizeRuntimeSegment(resolvePayloadSessionToken(payload), '')
-  if (payloadToken) return { session: payloadToken, sessionMode: 'host-session' }
-
   const payloadAlias = sanitizeRuntimeSegment(payload?._helloagentsSessionAlias, '')
+  if (payloadToken) {
+    return {
+      session: buildScopedSessionToken('host', payloadToken),
+      sessionMode: 'host-session',
+    }
+  }
+
   const payloadAliasToken = resolveActiveAliasSession({
     activationDir,
     projectRoot,
@@ -419,8 +476,15 @@ function chooseProjectSession({ payload, env, activationDir, projectRoot, worksp
     alias: payloadAlias,
   })
   if (payloadAliasToken) return { session: payloadAliasToken, sessionMode: 'active-session' }
+  if (payloadAlias) {
+    return {
+      session: buildScopedSessionToken('alias', payloadAlias),
+      sessionMode: 'alias-session',
+    }
+  }
 
   const envToken = sanitizeRuntimeSegment(resolveEnvSessionToken(env), '')
+  const envAliasToken = sanitizeRuntimeSegment(resolveEnvSessionAliasToken(env), '')
   const aliasToken = resolveActiveAliasSession({
     activationDir,
     projectRoot,
@@ -429,12 +493,37 @@ function chooseProjectSession({ payload, env, activationDir, projectRoot, worksp
   })
   if (aliasToken) return { session: aliasToken, sessionMode: 'active-session' }
 
-  if (envToken) return { session: envToken, sessionMode: 'host-session' }
+  if (envToken) {
+    return {
+      session: buildScopedSessionToken('host', envToken),
+      sessionMode: 'host-session',
+    }
+  }
 
-  const activeToken = resolveActiveSessionToken({ activationDir, projectRoot, workspace })
-  if (activeToken) return { session: activeToken, sessionMode: 'active-session' }
+  if (envAliasToken) {
+    const activeAliasToken = resolveActiveAliasSession({
+      activationDir,
+      projectRoot,
+      workspace,
+      alias: envAliasToken,
+    })
+    if (activeAliasToken) return { session: activeAliasToken, sessionMode: 'active-session' }
+    return {
+      session: buildScopedSessionToken('alias', envAliasToken),
+      sessionMode: 'alias-session',
+    }
+  }
+
+  return { session: '', sessionMode: 'unidentified' }
+}
 
-  return { session: DEFAULT_STATE_SESSION_TOKEN, sessionMode: 'default' }
+function removeLegacyProjectArtifacts(activationDir) {
+  if (!activationDir) return
+  const artifactsDir = join(activationDir, PROJECT_ARTIFACTS_DIR_NAME)
+  if (!existsSync(artifactsDir)) return
+  try {
+    rmSync(artifactsDir, { recursive: true, force: true })
+  } catch {}
 }
 
 export function getProjectSessionScope(cwd, options = {}) {
@@ -442,6 +531,8 @@ export function getProjectSessionScope(cwd, options = {}) {
   const projectRoot = getProjectRoot(normalizedCwd)
   const { payload = {}, env = process.env } = normalizeRuntimeOptions(options)
   const activationDir = getProjectActivationDir(projectRoot)
+  removeLegacyProjectArtifacts(activationDir)
+  removeLegacySessionPointersFile(activationDir)
   const workspace = resolveWorkspaceName(projectRoot)
   const { session, sessionMode } = chooseProjectSession({
     payload,
@@ -450,7 +541,8 @@ export function getProjectSessionScope(cwd, options = {}) {
     projectRoot,
     workspace,
   })
-  const sessionDir = join(activationDir, PROJECT_SESSIONS_DIR_NAME, workspace, session)
+  const workspaceDir = join(activationDir, PROJECT_SESSIONS_DIR_NAME, workspace)
+  const sessionDir = session ? join(workspaceDir, session) : join(workspaceDir, DEFAULT_STATE_SESSION_TOKEN)
 
   return {
     cwd: projectRoot,
@@ -461,10 +553,12 @@ export function getProjectSessionScope(cwd, options = {}) {
     sessionMode,
     activationDir,
     sessionDir,
+    workspaceDir,
     statePath: join(sessionDir, 'STATE.md'),
     eventsPath: join(sessionDir, EVENTS_FILE_NAME),
     artifactsDir: join(sessionDir, PROJECT_ARTIFACTS_DIR_NAME),
-    key: `${projectRoot}::${workspace}::${session}`,
+    runtimePath: join(sessionDir, PROJECT_RUNTIME_FILE_NAME),
+    key: `${projectRoot}::${workspace}::${session || DEFAULT_STATE_SESSION_TOKEN}`,
   }
 }
 
@@ -494,6 +588,7 @@ function buildTransientRuntimeDir(cwd, options = {}) {
     statePath: join(getUserRuntimeRoot(), hash, 'STATE.md'),
     eventsPath: join(getUserRuntimeRoot(), hash, EVENTS_FILE_NAME),
     artifactsDir: join(getUserRuntimeRoot(), hash, PROJECT_ARTIFACTS_DIR_NAME),
+    runtimePath: join(getUserRuntimeRoot(), hash, PROJECT_RUNTIME_FILE_NAME),
     key: `${normalizedCwd}::transient::${token}`,
   }
 }

package/scripts/runtime-ttl.mjs

@@ -1,7 +1,10 @@
 export const LONG_RUNNING_TTL_HOURS = 720
 export const LONG_RUNNING_TTL_MS = LONG_RUNNING_TTL_HOURS * 60 * 60 * 1000
 
-export const ROUTE_CONTEXT_TTL_MS = LONG_RUNNING_TTL_MS
-export const TURN_STATE_TTL_MS = LONG_RUNNING_TTL_MS
-export const EVIDENCE_MAX_AGE_MS = LONG_RUNNING_TTL_MS
-export const USER_RUNTIME_MAX_AGE_MS = LONG_RUNNING_TTL_MS
+export const STANDARD_RUNTIME_TTL_HOURS = 72
+export const STANDARD_RUNTIME_TTL_MS = STANDARD_RUNTIME_TTL_HOURS * 60 * 60 * 1000
+
+export const ROUTE_CONTEXT_TTL_MS = STANDARD_RUNTIME_TTL_MS
+export const TURN_STATE_TTL_MS = STANDARD_RUNTIME_TTL_MS
+export const EVIDENCE_MAX_AGE_MS = STANDARD_RUNTIME_TTL_MS
+export const USER_RUNTIME_MAX_AGE_MS = STANDARD_RUNTIME_TTL_MS

package/scripts/session-capsule.mjs

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
 import { basename, dirname, join } from 'node:path'
 
 import {
@@ -31,6 +31,79 @@ function buildEmptyCapsule(scope) {
   }
 }
 
+function readRuntimeDocument(filePath) {
+  const payload = readJsonFile(filePath, null)
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return null
+  }
+  return payload
+}
+
+function writeRuntimeDocument(filePath, payload) {
+  writeJsonFileAtomic(filePath, payload)
+}
+
+function isSamePath(left = '', right = '') {
+  if (process.platform === 'win32') {
+    return left.toLowerCase() === right.toLowerCase()
+  }
+  return left === right
+}
+
+function isSeedOnlyState(body = '') {
+  return String(body || '').includes('由运行时自动创建；后续按实际任务重写')
+}
+
+function looksLikeLegacyFlattenedSessionDir(entryName = '') {
+  return /^[a-z0-9]{8}$/i.test(String(entryName || '').trim())
+}
+
+function migrateLegacyProjectScope(scope) {
+  if (scope.scope !== 'project-session') return
+  const workspaceDir = scope.workspaceDir || join(scope.activationDir, 'sessions', scope.workspace || scope.branch)
+  const legacyStatePath = join(workspaceDir, 'STATE.md')
+  const legacyRuntimePath = join(workspaceDir, 'runtime.json')
+  if (isSamePath(workspaceDir, scope.sessionDir)) return
+
+  const currentDocument = readStateDocument(scope.statePath)
+  const currentCapsule = currentDocument.metadata && typeof currentDocument.metadata === 'object'
+    ? currentDocument.metadata
+    : null
+  const legacyDocument = readStateDocument(legacyStatePath)
+  const legacyCapsule = readRuntimeDocument(legacyRuntimePath)
+  const shouldNormalizeCurrentBody = currentDocument.hasMetadata
+  const shouldWriteBody = (!currentDocument.body.trim() && legacyDocument.body.trim()) || shouldNormalizeCurrentBody
+  const shouldWriteRuntime = (legacyCapsule || currentCapsule) && !readRuntimeDocument(scope.runtimePath)
+
+  if (shouldWriteBody) {
+    writeStateDocument(scope.statePath, {
+      body: currentDocument.body.trim() ? currentDocument.body : legacyDocument.body,
+    })
+  }
+  if (shouldWriteRuntime) {
+    writeRuntimeDocument(scope.runtimePath, legacyCapsule || currentCapsule)
+  }
+
+  if (existsSync(legacyStatePath) && shouldWriteBody) {
+    const legacyCurrent = readStateDocument(legacyStatePath)
+    if (legacyCurrent.hasMetadata) {
+      writeStateDocument(legacyStatePath, {
+        body: legacyCurrent.body,
+      })
+    }
+  }
+  if (existsSync(legacyRuntimePath) && shouldWriteRuntime) {
+    rmSync(legacyRuntimePath, { force: true })
+  }
+  if (existsSync(workspaceDir)) {
+    for (const entry of readdirSync(workspaceDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      if (!looksLikeLegacyFlattenedSessionDir(entry.name)) continue
+      rmSync(join(workspaceDir, entry.name), { recursive: true, force: true })
+    }
+  }
+}
+
 function normalizeOptions(options = {}) {
   if (!options || typeof options !== 'object') return {}
   if (options.payload && typeof options.payload === 'object') return options
@@ -68,8 +141,23 @@ function getScope(cwd, options = {}) {
   return getRuntimeScope(cwd, normalizedOptions)
 }
 
+function shouldMaterializeSessionState(options = {}) {
+  const normalizedOptions = normalizeOptions(options)
+  if (normalizedOptions.ensureProjectLocal === true) return true
+  if (normalizedOptions.project === true) return true
+  if (normalizedOptions.traceEvents === true) return true
+
+  const payload = normalizedOptions.payload || {}
+  if (payload.traceEvents === true || payload._helloagentsTraceEvents === true) return true
+
+  const raw = String(normalizedOptions.env?.HELLOAGENTS_TRACE_EVENTS || process.env.HELLOAGENTS_TRACE_EVENTS || '')
+    .trim()
+    .toLowerCase()
+  return raw === '1' || raw === 'true' || raw === 'yes'
+}
+
 export function getSessionCapsulePath(cwd = process.cwd(), options = {}) {
-  return getScope(cwd, options).statePath
+  return getScope(cwd, options).runtimePath
 }
 
 export function getSessionEventsPath(cwd = process.cwd(), options = {}) {
@@ -87,15 +175,15 @@ export function getSessionArtifactPath(cwd, fileName, options = {}) {
 export function getSessionArtifactRelativePath(cwd, fileName, options = {}) {
   const scope = getScope(cwd, options)
   if (scope.scope === 'project-session') {
-    return `.helloagents/sessions/${scope.workspace || scope.branch}/${scope.session}/artifacts/${fileName}`
+    return `.helloagents/sessions/${scope.workspace || scope.branch}/${scope.session || 'default'}/artifacts/${fileName}`
   }
   return `~/.helloagents/runtime/${basename(scope.sessionDir)}/artifacts/${fileName}`
 }
 
 export function readSessionCapsule(cwd = process.cwd(), options = {}) {
   const scope = getScope(cwd, options)
-  const { metadata } = readStateDocument(scope.statePath)
-  const capsule = metadata && typeof metadata === 'object' ? metadata : null
+  migrateLegacyProjectScope(scope)
+  const capsule = readRuntimeDocument(scope.runtimePath)
   if (!capsule || Array.isArray(capsule)) return buildEmptyCapsule(scope)
   return {
     ...buildEmptyCapsule(scope),
@@ -113,9 +201,11 @@ export function readSessionCapsule(cwd = process.cwd(), options = {}) {
 export function writeSessionCapsule(cwd, capsule, options = {}) {
   const normalizedOptions = normalizeOptions(options)
   const scope = getScope(cwd, normalizedOptions)
+  migrateLegacyProjectScope(scope)
+  const shouldMaterialize = shouldMaterializeSessionState(normalizedOptions)
   const currentDocument = readStateDocument(scope.statePath)
   const hasBody = Boolean(currentDocument.body && currentDocument.body.trim())
-  if (!hasBody && normalizedOptions.ensureProjectLocal !== true && !existsSync(scope.statePath)) {
+  if (!hasBody && !shouldMaterialize && !existsSync(scope.statePath)) {
     return {
       ...buildEmptyCapsule(scope),
       ...capsule,
@@ -129,6 +219,14 @@ export function writeSessionCapsule(cwd, capsule, options = {}) {
       updatedAt: new Date().toISOString(),
     }
   }
+  if (!hasBody && shouldMaterialize && !existsSync(scope.statePath)) {
+    ensureProjectLocalRuntime(cwd, {
+      ...normalizedOptions,
+      stateSeed: normalizedOptions.stateSeed && typeof normalizedOptions.stateSeed === 'object'
+        ? normalizedOptions.stateSeed
+        : {},
+    })
+  }
   const nextCapsule = {
     ...buildEmptyCapsule(scope),
     ...capsule,
@@ -141,10 +239,12 @@ export function writeSessionCapsule(cwd, capsule, options = {}) {
     sessionMode: scope.sessionMode,
     updatedAt: new Date().toISOString(),
   }
-  writeStateDocument(scope.statePath, {
-    metadata: nextCapsule,
-    body: currentDocument.body,
-  })
+  writeRuntimeDocument(scope.runtimePath, nextCapsule)
+  if (hasBody) {
+    writeStateDocument(scope.statePath, {
+      body: currentDocument.body,
+    })
+  }
   writeActiveProjectSession(scope, {
     env: normalizedOptions.env,
   })
@@ -173,8 +273,8 @@ export function writeCapsuleSection(cwd, section, value, options = {}) {
 }
 
 export function clearCapsuleSection(cwd, section, options = {}) {
-  const statePath = getSessionCapsulePath(cwd, options)
-  if (!existsSync(statePath)) return false
+  const runtimePath = getSessionCapsulePath(cwd, options)
+  if (!existsSync(runtimePath)) return false
 
   const capsule = readSessionCapsule(cwd, options)
   if (!Object.prototype.hasOwnProperty.call(capsule, section)) return false
@@ -265,7 +365,11 @@ export function clearSessionArtifact(cwd, fileName, options = {}) {
 }
 
 export function removeSessionCapsule(cwd, options = {}) {
-  removeRuntimeFile(getSessionCapsulePath(cwd, options))
+  const scope = getScope(cwd, options)
+  removeRuntimeFile(scope.runtimePath)
+  if (scope.scope !== 'project-session') {
+    removeRuntimeFile(scope.statePath)
+  }
 }
 
 function shouldRecordSessionEvents(options = {}) {