helloagents 3.0.33 → 3.0.37

package/scripts/qa-review-state.mjs

@@ -0,0 +1,313 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { appendReplayEvent } from './replay-state.mjs'
+import {
+  captureWorkspaceFingerprint,
+  clearRuntimeEvidence,
+  getRuntimeEvidencePath,
+  getRuntimeEvidenceRelativePath,
+  readRuntimeEvidence,
+  validateEvidenceFingerprint,
+  validateEvidenceTimestamp,
+  writeRuntimeEvidence,
+} from './runtime-artifacts.mjs'
+import { getProjectVerifyYamlPath } from './project-storage.mjs'
+
+export const QA_REVIEW_EVIDENCE_FILE_NAME = 'qa-review.json'
+const VALID_QA_MODES = new Set(['standard', 'deep'])
+const VALID_QA_OUTCOMES = new Set(['clean', 'findings'])
+const SHELL_OPERATORS = /[;&|`$(){}\n\r]/
+
+function normalizeStringArray(values) {
+  if (!Array.isArray(values)) return []
+  return [...new Set(values
+    .map((value) => (typeof value === 'string' ? value.trim() : ''))
+    .filter(Boolean))]
+}
+
+function normalizeQaMode(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : ''
+  return VALID_QA_MODES.has(normalized) ? normalized : ''
+}
+
+function normalizeQaOutcome(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : ''
+  return VALID_QA_OUTCOMES.has(normalized) ? normalized : ''
+}
+
+function normalizeCommands(values) {
+  return normalizeStringArray(values)
+}
+
+function loadVerifyYaml(cwd) {
+  const filePath = getProjectVerifyYamlPath(cwd)
+  if (!existsSync(filePath)) return null
+  try {
+    const content = readFileSync(filePath, 'utf-8')
+    const commands = []
+    let inCommands = false
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim()
+      if (trimmed.startsWith('commands:')) {
+        inCommands = true
+        continue
+      }
+      if (!inCommands) continue
+      if (trimmed.startsWith('- ') && !trimmed.startsWith('# ')) {
+        const command = trimmed.slice(2).trim().replace(/^["']|["']$/g, '')
+        if (command && !command.startsWith('#')) commands.push(command)
+        continue
+      }
+      if (trimmed && !trimmed.startsWith('#')) break
+    }
+    return commands.length > 0 ? commands : null
+  } catch {
+    return null
+  }
+}
+
+function detectFromPackageJson(cwd) {
+  const filePath = join(cwd, 'package.json')
+  if (!existsSync(filePath)) return []
+  try {
+    const scripts = JSON.parse(readFileSync(filePath, 'utf-8')).scripts || {}
+    return ['lint', 'typecheck', 'type-check', 'test', 'build']
+      .filter((key) => key in scripts)
+      .map((key) => `npm run ${key}`)
+  } catch {
+    return []
+  }
+}
+
+function detectFromPyproject(cwd) {
+  const filePath = join(cwd, 'pyproject.toml')
+  if (!existsSync(filePath)) return []
+  try {
+    const content = readFileSync(filePath, 'utf-8')
+    const commands = []
+    if (content.includes('[tool.ruff')) commands.push('ruff check .')
+    if (content.includes('[tool.mypy')) commands.push('mypy .')
+    if (content.includes('[tool.pytest')) commands.push('pytest --tb=short -q')
+    return commands
+  } catch {
+    return []
+  }
+}
+
+export function detectCommands(cwd) {
+  const yamlCommands = loadVerifyYaml(cwd)
+  if (yamlCommands?.length) return yamlCommands
+  const packageJsonCommands = detectFromPackageJson(cwd)
+  if (packageJsonCommands.length > 0) return packageJsonCommands
+  return detectFromPyproject(cwd)
+}
+
+export function hasUnsafeQaCommand(commands = []) {
+  return commands.some((command) => SHELL_OPERATORS.test(command))
+}
+
+export function getQaReviewEvidencePath(cwd, options = {}) {
+  return getRuntimeEvidencePath(cwd, QA_REVIEW_EVIDENCE_FILE_NAME, options)
+}
+
+export function readQaReviewEvidence(cwd, options = {}) {
+  return readRuntimeEvidence(cwd, QA_REVIEW_EVIDENCE_FILE_NAME, options)
+}
+
+export function clearQaReviewEvidence(cwd, options = {}) {
+  clearRuntimeEvidence(cwd, QA_REVIEW_EVIDENCE_FILE_NAME, options)
+}
+
+export function normalizeQaReviewEvidence(input = {}) {
+  return {
+    source: typeof input.source === 'string' && input.source.trim() ? input.source.trim() : 'manual',
+    originCommand: typeof input.originCommand === 'string' ? input.originCommand.trim() : '',
+    qaMode: normalizeQaMode(input.qaMode) || 'standard',
+    scope: typeof input.scope === 'string' ? input.scope.trim() : '',
+    outcome: normalizeQaOutcome(input.outcome),
+    conclusion: typeof input.conclusion === 'string' ? input.conclusion.trim() : '',
+    findings: normalizeStringArray(input.findings),
+    fileReferences: normalizeStringArray(input.fileReferences),
+    commands: normalizeCommands(input.commands),
+    fastOnly: Boolean(input.fastOnly),
+  }
+}
+
+export function writeQaReviewEvidence(cwd, {
+  source = 'manual',
+  originCommand = '',
+  qaMode = 'standard',
+  scope = '',
+  outcome = '',
+  conclusion = '',
+  findings = [],
+  fileReferences = [],
+  commands = [],
+  fastOnly = false,
+} = {}, options = {}) {
+  const normalized = normalizeQaReviewEvidence({
+    source,
+    originCommand,
+    qaMode,
+    scope,
+    outcome,
+    conclusion,
+    findings,
+    fileReferences,
+    commands,
+    fastOnly,
+  })
+  const payload = {
+    schemaVersion: 2,
+    updatedAt: new Date().toISOString(),
+    source: normalized.source,
+    originCommand: normalized.originCommand,
+    qaMode: normalized.qaMode,
+    scope: normalized.scope,
+    outcome: normalized.outcome,
+    conclusion: normalized.conclusion,
+    findings: normalized.findings,
+    fileReferences: normalized.fileReferences,
+    commands: normalized.commands,
+    fastOnly: normalized.fastOnly,
+    fingerprint: captureWorkspaceFingerprint(cwd),
+  }
+  writeRuntimeEvidence(cwd, QA_REVIEW_EVIDENCE_FILE_NAME, payload, options)
+  appendReplayEvent(cwd, {
+    event: 'qa_review_evidence_written',
+    source: normalized.source,
+    skillName: normalized.originCommand,
+    payload: options.payload || {},
+    details: {
+      qaMode: normalized.qaMode,
+      scope: normalized.scope,
+      outcome: normalized.outcome,
+      conclusion: normalized.conclusion,
+      findings: normalized.findings,
+      fileReferences: normalized.fileReferences,
+      commands: normalized.commands,
+      fastOnly: normalized.fastOnly,
+    },
+    artifacts: [getRuntimeEvidenceRelativePath(cwd, QA_REVIEW_EVIDENCE_FILE_NAME, options)],
+  })
+  return payload
+}
+
+function readRequiredQaReviewEvidence(cwd, options = {}) {
+  const evidence = readQaReviewEvidence(cwd, options)
+  if (evidence) return { evidence }
+  return {
+    error: {
+      required: true,
+      status: 'missing',
+      details: ['缺少当前工作流的成功 qa-review 证据'],
+    },
+  }
+}
+
+function validateQaReviewTimestamp(evidence, now) {
+  return validateEvidenceTimestamp(evidence, now, 'qa-review 证据')
+}
+
+function validateQaReviewFingerprint(cwd, evidence) {
+  return validateEvidenceFingerprint(cwd, evidence, '成功 qa-review 证据')
+}
+
+function validateQaReviewEvidence(commands, evidence) {
+  if (!normalizeQaOutcome(evidence.outcome) || !String(evidence.conclusion || '').trim()) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      commands,
+      details: ['qa-review 证据必须记录明确的 outcome 和 conclusion'],
+    }
+  }
+  if (commands.length > 0 && normalizeCommands(evidence.commands).length === 0) {
+    return {
+      required: true,
+      status: 'invalid',
+      evidence,
+      commands,
+      details: ['qa-review 证据必须记录本次实际执行的验证命令'],
+    }
+  }
+  if (Boolean(evidence.fastOnly)) {
+    return {
+      required: true,
+      status: 'fast-only',
+      evidence,
+      commands,
+      details: ['最新 qa-review 证据只覆盖快速命令检查，未完成完整 qa-review 闭环'],
+    }
+  }
+  if (normalizeQaOutcome(evidence.outcome) !== 'clean') {
+    return {
+      required: true,
+      status: 'blocked',
+      evidence,
+      commands,
+      details: ['最新 qa-review 证据仍记录阻断问题'],
+    }
+  }
+  return null
+}
+
+export function getQaReviewEvidenceStatus(cwd, { required = false, now = Date.now(), ...options } = {}) {
+  const commands = detectCommands(cwd)
+  if (!required) {
+    return {
+      required: false,
+      status: 'not-applicable',
+      commands,
+    }
+  }
+
+  const requiredEvidence = readRequiredQaReviewEvidence(cwd, options)
+  if (requiredEvidence.error) return { ...requiredEvidence.error, commands }
+
+  const { evidence } = requiredEvidence
+  const timestampError = validateQaReviewTimestamp(evidence, now)
+  if (timestampError) return { ...timestampError, commands }
+
+  const fingerprintError = validateQaReviewFingerprint(cwd, evidence)
+  if (fingerprintError) return { ...fingerprintError, commands }
+
+  const evidenceError = validateQaReviewEvidence(commands, evidence)
+  if (evidenceError) return evidenceError
+
+  return {
+    required: true,
+    status: 'valid',
+    evidence,
+    commands,
+  }
+}
+
+function readStdinJson() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function main() {
+  const command = process.argv[2] || ''
+  if (command !== 'write') return
+
+  const input = readStdinJson()
+  const cwd = input.cwd || process.cwd()
+  const payload = writeQaReviewEvidence(cwd, input, { payload: input })
+  process.stdout.write(JSON.stringify({
+    suppressOutput: true,
+    path: getQaReviewEvidencePath(cwd, { payload: input }),
+    payload,
+  }))
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}

package/scripts/ralph-loop.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * HelloAGENTS Ralph Loop — Quality verification gate
+ * HelloAGENTS QA Gate — Quality verification gate
  * Runs on SubagentStop (Claude Code) and Stop (Codex CLI).
  * Auto-detects lint/test commands and blocks if they fail.
  */
@@ -9,7 +9,13 @@ import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { clearVerifyEvidence, detectCommands, hasUnsafeVerifyCommand, writeVerifyEvidence } from './verify-state.mjs';
+import {
+  clearQaReviewEvidence,
+  detectCommands,
+  getQaReviewEvidenceStatus,
+  hasUnsafeQaCommand,
+  writeQaReviewEvidence,
+} from './qa-review-state.mjs';
 import {
   getRuntimeEvidencePath,
   readRuntimeEvidence,
@@ -70,7 +76,7 @@ function hasGitChanges(cwd) {
 function runVerify(commands, cwd) {
   const failures = [];
   for (const cmd of commands) {
-    if (hasUnsafeVerifyCommand([cmd])) {
+    if (hasUnsafeQaCommand([cmd])) {
       failures.push({ cmd, output: '已阻止：验证命令不允许使用 shell 组合操作符' });
       continue;
     }
@@ -219,17 +225,30 @@ export function evaluateRalphLoop(data = {}, runtime = {}) {
   const failures = runVerify(commands, cwd);
   if (failures.length === 0) {
     resetBreaker(cwd, runtimeOptions);
-    writeVerifyEvidence(cwd, {
-      commands: detectCommands(cwd),
-      fastOnly: isSubagent,
-      source: isSubagent ? 'subagent' : 'stop',
-    }, runtimeOptions);
+    const qaStatus = getQaReviewEvidenceStatus(cwd, {
+      required: true,
+      ...runtimeOptions,
+    });
+    if (qaStatus.status !== 'valid') {
+      writeQaReviewEvidence(cwd, {
+        source: isSubagent ? 'subagent' : 'ralph-loop',
+        originCommand: 'qa',
+        qaMode: 'standard',
+        scope: isSubagent ? 'subagent-fast-check' : 'runtime-fast-check',
+        outcome: 'clean',
+        conclusion: '自动命令检查通过。',
+        findings: [],
+        fileReferences: [],
+        commands: detectCommands(cwd),
+        fastOnly: true,
+      }, runtimeOptions);
+    }
 
     if (isSubagent) {
       return {
         hookSpecificOutput: {
           hookEventName,
-          additionalContext: '子代理快速验证通过（lint/typecheck）。请控制器审查变更后继续。',
+          additionalContext: '子代理快速 QA 命令检查通过（lint/typecheck）。请控制器继续完整 qa-review。',
         },
         suppressOutput: true,
       };
@@ -239,7 +258,7 @@ export function evaluateRalphLoop(data = {}, runtime = {}) {
       return {
         hookSpecificOutput: {
           hookEventName,
-          additionalContext: '⚠️ [Ralph Loop] 验证通过但未检测到代码变更（git diff 为空）。如果确实完成了编码任务，请确认变更已保存。',
+          additionalContext: '⚠️ [QA Gate] 验证通过但未检测到代码变更（git diff 为空）。如果确实完成了编码任务，请确认变更已保存。',
         },
         suppressOutput: true,
       };
@@ -248,7 +267,7 @@ export function evaluateRalphLoop(data = {}, runtime = {}) {
     return { suppressOutput: true };
   }
 
-  clearVerifyEvidence(cwd, runtimeOptions);
+  clearQaReviewEvidence(cwd, runtimeOptions);
   const breaker = readBreaker(cwd, runtimeOptions);
   breaker.consecutive_failures += 1;
   breaker.last_failure = new Date().toISOString();
@@ -260,7 +279,7 @@ export function evaluateRalphLoop(data = {}, runtime = {}) {
   const details = failures.map(f => `\u2717 ${f.cmd}\n${f.output}`).join('\n\n');
   return {
     decision: 'block',
-    reason: `[Ralph Loop] 验证失败：\n\n${details}\n\n请先修复以上问题，再报告完成。${breakerWarning}`,
+    reason: `[QA Gate] 验证失败：\n\n${details}\n\n请先修复以上问题，再报告完成。${breakerWarning}`,
     suppressOutput: true,
   };
 }
@@ -278,7 +297,7 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
   } catch (error) {
     process.stdout.write(JSON.stringify({
       decision: 'block',
-      reason: `[Ralph Loop] 验证脚本执行异常，已暂停完成通知。\n原因：${error?.message || error}`,
+      reason: `[QA Gate] 验证脚本执行异常，已暂停完成通知。\n原因：${error?.message || error}`,
       suppressOutput: true,
     }));
   }

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,7 +4,7 @@ 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 { 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'
@@ -12,7 +12,6 @@ import { FULL_CARRIER_PROFILE_MARKER } from './cli-utils.mjs'
 export const PROJECT_DIR_NAME = '.helloagents'
 export const PROJECT_SESSIONS_DIR_NAME = 'sessions'
 export const PROJECT_ARTIFACTS_DIR_NAME = 'artifacts'
-export const CAPSULE_FILE_NAME = 'capsule.json'
 export const EVENTS_FILE_NAME = 'events.jsonl'
 export const ACTIVE_SESSION_FILE_NAME = 'active.json'
 export const DEFAULT_STATE_SESSION_TOKEN = 'default'
@@ -324,21 +323,14 @@ 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 resolveTransientSessionToken({ payload = {}, env = process.env, ppid = process.ppid } = {}) {
@@ -438,11 +430,21 @@ function chooseProjectSession({ payload, env, activationDir, projectRoot, worksp
   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 = {}) {
   const normalizedCwd = normalizePath(cwd || process.cwd())
   const projectRoot = getProjectRoot(normalizedCwd)
   const { payload = {}, env = process.env } = normalizeRuntimeOptions(options)
   const activationDir = getProjectActivationDir(projectRoot)
+  removeLegacyProjectArtifacts(activationDir)
   const workspace = resolveWorkspaceName(projectRoot)
   const { session, sessionMode } = chooseProjectSession({
     payload,
@@ -463,7 +465,6 @@ export function getProjectSessionScope(cwd, options = {}) {
     activationDir,
     sessionDir,
     statePath: join(sessionDir, 'STATE.md'),
-    capsulePath: join(sessionDir, CAPSULE_FILE_NAME),
     eventsPath: join(sessionDir, EVENTS_FILE_NAME),
     artifactsDir: join(sessionDir, PROJECT_ARTIFACTS_DIR_NAME),
     key: `${projectRoot}::${workspace}::${session}`,
@@ -493,7 +494,7 @@ function buildTransientRuntimeDir(cwd, options = {}) {
     session: token,
     sessionMode: token === DEFAULT_STATE_SESSION_TOKEN ? 'default' : 'transient-session',
     sessionDir: join(getUserRuntimeRoot(), hash),
-    capsulePath: join(getUserRuntimeRoot(), hash, CAPSULE_FILE_NAME),
+    statePath: join(getUserRuntimeRoot(), hash, 'STATE.md'),
     eventsPath: join(getUserRuntimeRoot(), hash, EVENTS_FILE_NAME),
     artifactsDir: join(getUserRuntimeRoot(), hash, PROJECT_ARTIFACTS_DIR_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

@@ -10,6 +10,7 @@ import {
   writeActiveProjectSession,
   writeJsonFileAtomic,
 } from './runtime-scope.mjs'
+import { readStateDocument, writeStateDocument } from './state-document.mjs'
 
 export { getRuntimeScope }
 
@@ -67,8 +68,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).capsulePath
+  return getScope(cwd, options).statePath
 }
 
 export function getSessionEventsPath(cwd = process.cwd(), options = {}) {
@@ -93,8 +109,9 @@ export function getSessionArtifactRelativePath(cwd, fileName, options = {}) {
 
 export function readSessionCapsule(cwd = process.cwd(), options = {}) {
   const scope = getScope(cwd, options)
-  const capsule = readJsonFile(scope.capsulePath, null)
-  if (!capsule || typeof capsule !== 'object') return buildEmptyCapsule(scope)
+  const { metadata } = readStateDocument(scope.statePath)
+  const capsule = metadata && typeof metadata === 'object' ? metadata : null
+  if (!capsule || Array.isArray(capsule)) return buildEmptyCapsule(scope)
   return {
     ...buildEmptyCapsule(scope),
     ...capsule,
@@ -109,7 +126,33 @@ export function readSessionCapsule(cwd = process.cwd(), options = {}) {
 }
 
 export function writeSessionCapsule(cwd, capsule, options = {}) {
-  const scope = getScope(cwd, options)
+  const normalizedOptions = normalizeOptions(options)
+  const scope = getScope(cwd, normalizedOptions)
+  const shouldMaterialize = shouldMaterializeSessionState(normalizedOptions)
+  const currentDocument = readStateDocument(scope.statePath)
+  const hasBody = Boolean(currentDocument.body && currentDocument.body.trim())
+  if (!hasBody && !shouldMaterialize && !existsSync(scope.statePath)) {
+    return {
+      ...buildEmptyCapsule(scope),
+      ...capsule,
+      scope: scope.scope,
+      key: scope.key,
+      cwd: scope.cwd,
+      branch: scope.branch,
+      workspace: scope.workspace || scope.branch,
+      session: scope.session,
+      sessionMode: scope.sessionMode,
+      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,
@@ -122,9 +165,12 @@ export function writeSessionCapsule(cwd, capsule, options = {}) {
     sessionMode: scope.sessionMode,
     updatedAt: new Date().toISOString(),
   }
-  writeJsonFileAtomic(scope.capsulePath, nextCapsule)
+  writeStateDocument(scope.statePath, {
+    metadata: nextCapsule,
+    body: currentDocument.body,
+  })
   writeActiveProjectSession(scope, {
-    env: normalizeOptions(options).env,
+    env: normalizedOptions.env,
   })
   return nextCapsule
 }
@@ -151,8 +197,8 @@ export function writeCapsuleSection(cwd, section, value, options = {}) {
 }
 
 export function clearCapsuleSection(cwd, section, options = {}) {
-  const capsulePath = getSessionCapsulePath(cwd, options)
-  if (!existsSync(capsulePath)) return false
+  const statePath = getSessionCapsulePath(cwd, options)
+  if (!existsSync(statePath)) return false
 
   const capsule = readSessionCapsule(cwd, options)
   if (!Object.prototype.hasOwnProperty.call(capsule, section)) return false
@@ -180,6 +226,13 @@ export function appendSessionEvent(cwd, eventPayload, options = {}) {
   const eventName = eventPayload?.event || ''
   if (!eventName) return ''
 
+  writeActiveProjectSession(scope, {
+    host: eventPayload.host || '',
+    source: eventPayload.source || eventName,
+    env: scopedOptions.env,
+  })
+  if (!shouldRecordSessionEvents(scopedOptions)) return ''
+
   mkdirSync(dirname(scope.eventsPath), { recursive: true })
   const payload = {
     ts: new Date().toISOString(),
@@ -192,17 +245,13 @@ export function appendSessionEvent(cwd, eventPayload, options = {}) {
     encoding: 'utf-8',
     flag: 'a',
   })
-  writeActiveProjectSession(scope, {
-    host: eventPayload.host || '',
-    source: eventPayload.source || eventName,
-    env: scopedOptions.env,
-  })
   return scope.eventsPath
 }
 
 export function resetSessionEvents(cwd, options = {}) {
   const scope = getScope(cwd, options)
   if (scope.scope === 'project-session' && !scope.active) return ''
+  if (!shouldRecordSessionEvents(options)) return ''
   mkdirSync(dirname(scope.eventsPath), { recursive: true })
   writeFileSync(scope.eventsPath, '', 'utf-8')
   return scope.eventsPath
@@ -242,3 +291,16 @@ export function clearSessionArtifact(cwd, fileName, options = {}) {
 export function removeSessionCapsule(cwd, options = {}) {
   removeRuntimeFile(getSessionCapsulePath(cwd, options))
 }
+
+function shouldRecordSessionEvents(options = {}) {
+  const normalizedOptions = normalizeOptions(options)
+  const payload = normalizedOptions.payload || {}
+  if (normalizedOptions.traceEvents === true || 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'
+}