helloagents 3.0.33 → 3.0.35

package/scripts/delivery-gate-messages.mjs

@@ -24,10 +24,8 @@ function issueHeading(issue) {
       return '任务缺少可交付元数据'
     case 'missing-contract':
       return '方案包缺少可信的结构化契约'
-    case 'missing-verify-evidence':
-      return '当前工作流缺少最新验证证据'
-    case 'missing-review-evidence':
-      return '当前工作流缺少最新审查证据'
+    case 'missing-qa-review-evidence':
+      return '当前工作流缺少最新 qa-review 证据'
     case 'missing-advisor-evidence':
       return '当前工作流缺少最新 advisor 证据'
     case 'missing-visual-evidence':
@@ -62,6 +60,9 @@ export function buildDeliveryBlockReason(issues, recommendation, gateHint) {
   if (issues.some((issue) => issue.type === 'missing-visual-evidence')) {
     lines.push('视觉验收动作：先写入当前会话 `artifacts/visual.json`，记录 `tooling`、`screensChecked`、`statesChecked`、`status` 和 `summary`，再报告完成。')
   }
+  if (issues.some((issue) => issue.type === 'missing-qa-review-evidence')) {
+    lines.push('质量闭环动作：先完成 `~qa` 或写入当前会话 `artifacts/qa-review.json`，记录结论、问题定位、验证命令与最新结果，再报告完成。')
+  }
   if (gateHint) {
     lines.push(gateHint)
   }

package/scripts/delivery-gate.mjs

@@ -9,10 +9,9 @@ import { fileURLToPath } from 'node:url'
 import { getAdvisorEvidenceStatus } from './advisor-state.mjs'
 import { getCloseoutEvidenceStatus } from './closeout-state.mjs'
 import { getAdvisorRequirement, getVisualValidationRequirement } from './plan-contract.mjs'
+import { getQaReviewEvidenceStatus } from './qa-review-state.mjs'
 import { getVisualEvidenceStatus } from './visual-state.mjs'
 import { buildDeliveryGateHint, getDeliveryAction, getWorkflowRecommendation, getWorkflowSnapshot } from './workflow-state.mjs'
-import { getReviewEvidenceStatus } from './review-state.mjs'
-import { getVerifyEvidenceStatus } from './verify-state.mjs'
 import { buildDeliveryBlockReason, buildUnderSpecifiedDetails } from './delivery-gate-messages.mjs'
 
 function selectGatePlans(snapshot) {
@@ -84,20 +83,12 @@ function collectPlanIssues(planEntries) {
   return issues
 }
 
-function collectEvidenceIssues(issues, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus) {
-  if (verificationStatus?.required && verificationStatus.status !== 'valid') {
+function collectEvidenceIssues(issues, qaStatus, advisorStatus, visualStatus, closeoutStatus) {
+  if (qaStatus?.required && qaStatus.status !== 'valid') {
     issues.push({
-      type: 'missing-verify-evidence',
+      type: 'missing-qa-review-evidence',
       planName: 'delivery',
-      details: verificationStatus.details,
-    })
-  }
-
-  if (reviewStatus?.required && reviewStatus.status !== 'valid') {
-    issues.push({
-      type: 'missing-review-evidence',
-      planName: 'delivery',
-      details: reviewStatus.details,
+      details: qaStatus.details,
     })
   }
   if (advisorStatus?.required && advisorStatus.status !== 'valid') {
@@ -124,9 +115,9 @@ function collectEvidenceIssues(issues, verificationStatus, reviewStatus, advisor
   }
 }
 
-function collectGateIssues(planEntries, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus) {
+function collectGateIssues(planEntries, qaStatus, advisorStatus, visualStatus, closeoutStatus) {
   const issues = collectPlanIssues(planEntries)
-  collectEvidenceIssues(issues, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus)
+  collectEvidenceIssues(issues, qaStatus, advisorStatus, visualStatus, closeoutStatus)
   return issues
 }
 
@@ -143,11 +134,10 @@ export function evaluateDeliveryGate(data = {}) {
   const workflowOptions = { payload: data }
   const snapshot = getWorkflowSnapshot(cwd, workflowOptions)
   const recommendation = getWorkflowRecommendation(cwd, workflowOptions)
-  const verificationStatus = getVerifyEvidenceStatus(cwd, workflowOptions)
   const deliveryAction = getDeliveryAction(cwd, workflowOptions)
   const gatePlans = selectGatePlans(snapshot)
-  const reviewStatus = getReviewEvidenceStatus(cwd, {
-    required: deliveryAction?.phase === 'verify' && deliveryAction?.mode === 'review-first',
+  const qaStatus = getQaReviewEvidenceStatus(cwd, {
+    required: deliveryAction?.phase === 'qa' || deliveryAction?.phase === 'consolidate',
     ...workflowOptions,
   })
   if (gatePlans.length === 0) {
@@ -169,8 +159,7 @@ export function evaluateDeliveryGate(data = {}) {
   })
   const closeoutRequired = (
     gatePlans.every((entry) => entry.missingFiles.length === 0 && entry.templateIssues.length === 0 && entry.taskSummary.total > 0 && entry.taskSummary.open === 0 && entry.taskSummary.underSpecifiedCount === 0)
-    && (!verificationStatus.required || verificationStatus.status === 'valid')
-    && (!reviewStatus.required || reviewStatus.status === 'valid')
+    && (!qaStatus.required || qaStatus.status === 'valid')
     && (!advisorStatus.required || advisorStatus.status === 'valid')
     && (!visualStatus.required || visualStatus.status === 'valid')
   )
@@ -179,7 +168,7 @@ export function evaluateDeliveryGate(data = {}) {
     ...workflowOptions,
   })
 
-  const issues = collectGateIssues(gatePlans, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus)
+  const issues = collectGateIssues(gatePlans, qaStatus, advisorStatus, visualStatus, closeoutStatus)
   if (issues.length === 0) {
     return { suppressOutput: true }
   }

package/scripts/guard.mjs

@@ -76,7 +76,7 @@ function buildHighRiskGate(matches, cwd, payload = {}) {
   if (!recommendation) return null
   if (matches.some((match) => match.gate === 'post-verify')) {
     return {
-      reason: `[HelloAGENTS Guard] 已阻止 T3 命令：当前工作流尚未进入 VERIFY / CONSOLIDATE。\n当前工作流：${recommendation.summary}\n处理路径：${recommendation.nextPath}\n${recommendation.guidance}`,
+      reason: `[HelloAGENTS Guard] 已阻止 T3 命令：当前工作流尚未进入 QA / CONSOLIDATE。\n当前工作流：${recommendation.summary}\n处理路径：${recommendation.nextPath}\n${recommendation.guidance}`,
     }
   }
   if (matches.some((match) => match.gate === 'plan-first') && recommendation.nextCommand === 'plan') {

package/scripts/notify-closeout.mjs

@@ -1,15 +1,56 @@
 import { createHash } from 'node:crypto'
 import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
-import { dirname } from 'node:path'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
 
-import { getRuntimeEvidencePath, readRuntimeEvidence, writeRuntimeEvidence } from './runtime-artifacts.mjs'
-
-export const CODEX_CLOSEOUT_EVIDENCE_FILE = 'codex-native-stop.json'
-export const CODEX_QUICK_NOTIFY_EVIDENCE_FILE = 'codex-quick-notify.json'
-const CODEX_CLOSEOUT_LOCK_FILE = 'codex-native-stop.lock'
+export const CODEX_NOTIFY_STATE_FILE = 'notify-state.json'
+export const CODEX_NOTIFY_LOCK_FILE = 'notify.lock'
 const WEAK_KEY_TTL_MS = 10_000
 const LOCK_STALE_MS = 120_000
 
+function getHomeDir(env = process.env) {
+  return env.HOME || env.USERPROFILE || homedir()
+}
+
+export function getCodexNotifyDir(env = process.env) {
+  return join(getHomeDir(env), '.codex', '.helloagents')
+}
+
+export function getCodexNotifyStatePath(env = process.env) {
+  return join(getCodexNotifyDir(env), CODEX_NOTIFY_STATE_FILE)
+}
+
+export function getCodexNotifyLockPath(env = process.env) {
+  return join(getCodexNotifyDir(env), CODEX_NOTIFY_LOCK_FILE)
+}
+
+function readNotifyState(env = process.env) {
+  try {
+    const value = JSON.parse(readFileSync(getCodexNotifyStatePath(env), 'utf-8'))
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      return { version: 1, nativeStop: null, quickNotify: null }
+    }
+    return {
+      version: 1,
+      nativeStop: value.nativeStop && typeof value.nativeStop === 'object' ? value.nativeStop : null,
+      quickNotify: value.quickNotify && typeof value.quickNotify === 'object' ? value.quickNotify : null,
+    }
+  } catch {
+    return { version: 1, nativeStop: null, quickNotify: null }
+  }
+}
+
+function writeNotifyState(state, env = process.env) {
+  const filePath = getCodexNotifyStatePath(env)
+  mkdirSync(dirname(filePath), { recursive: true })
+  writeFileSync(filePath, `${JSON.stringify({
+    version: 1,
+    nativeStop: state?.nativeStop || null,
+    quickNotify: state?.quickNotify || null,
+  }, null, 2)}\n`, 'utf-8')
+  return filePath
+}
+
 function getTurnId(payload = {}) {
   return String(payload.turnId || payload.turn_id || payload['turn-id'] || '').trim()
 }
@@ -118,13 +159,10 @@ export function matchesCodexCloseoutEvidence(evidence, snapshot, now = Date.now(
   return intersects(snapshot.weakKeys, weakKeys)
 }
 
-/**
- * Try to claim the current Codex closeout so Stop and native notify handle one turn only once.
- */
 export function beginCodexCloseoutClaim(cwd, { payload = {}, turnState = null, source = '' } = {}) {
   const snapshot = buildCodexCloseoutSnapshot({ payload, turnState })
-  const lockPath = getRuntimeEvidencePath(cwd, CODEX_CLOSEOUT_LOCK_FILE, { payload })
-  const evidencePath = getRuntimeEvidencePath(cwd, CODEX_CLOSEOUT_EVIDENCE_FILE, { payload })
+  const lockPath = getCodexNotifyLockPath()
+  const evidencePath = getCodexNotifyStatePath()
   const now = Date.now()
   const lockPayload = {
     source,
@@ -164,8 +202,8 @@ export function beginCodexCloseoutClaim(cwd, { payload = {}, turnState = null, s
     }
   }
 
-  const evidence = readRuntimeEvidence(cwd, CODEX_CLOSEOUT_EVIDENCE_FILE, { payload })
-  if (matchesCodexCloseoutEvidence(evidence, snapshot, now)) {
+  const notifyState = readNotifyState()
+  if (matchesCodexCloseoutEvidence(notifyState.nativeStop, snapshot, now)) {
     releaseLockFile(lockPath)
     return {
       claimed: false,
@@ -186,15 +224,13 @@ export function beginCodexCloseoutClaim(cwd, { payload = {}, turnState = null, s
   }
 }
 
-/**
- * Persist the handled closeout fingerprint and release the in-flight lock.
- */
 export function finalizeCodexCloseoutClaim(claim, meta = {}) {
   if (!claim?.claimed) return
 
   try {
     if (meta.handled !== false) {
-      writeRuntimeEvidence(claim.cwd, CODEX_CLOSEOUT_EVIDENCE_FILE, {
+      const notifyState = readNotifyState()
+      notifyState.nativeStop = {
         version: 2,
         updatedAt: new Date().toISOString(),
         source: meta.source || claim.source || '',
@@ -205,7 +241,8 @@ export function finalizeCodexCloseoutClaim(claim, meta = {}) {
         messageHash: claim.snapshot.messageHash,
         strongKeys: claim.snapshot.strongKeys,
         weakKeys: claim.snapshot.weakKeys,
-      }, { payload: claim.payload })
+      }
+      writeNotifyState(notifyState)
     }
   } finally {
     releaseLockFile(claim.lockPath)
@@ -214,7 +251,8 @@ export function finalizeCodexCloseoutClaim(claim, meta = {}) {
 
 export function writeCodexQuickNotifyEvidence(cwd, { payload = {}, turnState = null, event = '' } = {}) {
   const snapshot = buildCodexCloseoutSnapshot({ payload, turnState })
-  return writeRuntimeEvidence(cwd, CODEX_QUICK_NOTIFY_EVIDENCE_FILE, {
+  const notifyState = readNotifyState()
+  notifyState.quickNotify = {
     version: 1,
     updatedAt: new Date().toISOString(),
     event,
@@ -223,11 +261,12 @@ export function writeCodexQuickNotifyEvidence(cwd, { payload = {}, turnState = n
     messageHash: snapshot.messageHash,
     strongKeys: snapshot.strongKeys,
     weakKeys: snapshot.weakKeys,
-  }, { payload })
+  }
+  return writeNotifyState(notifyState)
 }
 
 export function hasCodexQuickNotifyEvidence(cwd, { payload = {}, turnState = null } = {}) {
   const snapshot = buildCodexCloseoutSnapshot({ payload, turnState })
-  const evidence = readRuntimeEvidence(cwd, CODEX_QUICK_NOTIFY_EVIDENCE_FILE, { payload })
-  return matchesCodexCloseoutEvidence(evidence, snapshot)
+  const notifyState = readNotifyState()
+  return matchesCodexCloseoutEvidence(notifyState.quickNotify, snapshot)
 }

package/scripts/notify-context.mjs

@@ -11,7 +11,7 @@ import {
 const COMMAND_ALIASES = {
   do: 'build',
   design: 'plan',
-  review: 'verify',
+  review: 'qa',
 };
 
 function buildRuntimeRootBlock(pkgRoot) {
@@ -49,7 +49,7 @@ function buildAliasRouteNote(skillName) {
     return '兼容别名映射：本次按 ~plan 规则执行；方案文件使用 `plan.md`，项目级 UI 契约仍使用 `DESIGN.md`。';
   }
   if (skillName === 'review') {
-    return '兼容别名映射：本次按 ~verify 的审查优先模式执行。';
+    return '兼容别名映射：本次按 ~qa 规则执行；统一走 qa-review 质量闭环。';
   }
   return '';
 }
@@ -137,7 +137,7 @@ export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host,
   if (capabilityHint) context += `\n\n## 当前按需能力\n${capabilityHint}`;
   if (stateSyncHint) context += `\n\n## 状态文件提醒\n${stateSyncHint}`;
   context += settingsBlock;
-  if (source === 'resume' || source === 'compact') {
+  if ((source === 'resume' || source === 'compact') && stateSnapshot.exists) {
     context += `\n\n> ⚠️ 会话已恢复/压缩，请先读取 \`state_path\` 指向的 \`${stateSnapshot.statePath.replace(/\\/g, '/')}\`；先看当前用户消息，如果仍是同一任务，再参考状态文件。`;
   }
   return context;
@@ -165,8 +165,8 @@ export function buildSemanticRouteInstruction(cwd, payload = {}) {
     '请根据用户请求的真实意图选路，不依赖关键词表。',
     buildDelegatedTaskHint(),
     'Delivery Tier: T0=探索/比较；T1=低风险小改动或显式验证；T2=多文件功能/新项目/需要结构化产物；T3=高风险或不可逆操作。',
-    '路由映射：~idea=只读探索，不创建文件；~build=明确实现；~verify=审查/验证；~plan=结构化规划；~prd=重型规格；~auto=自动选择并继续执行后续阶段。',
-    '若判定为 T3，默认先走 ~plan / ~prd；纯审查/验证请求才优先 ~verify。',
+    '路由映射：~idea=只读探索，不创建文件；~build=明确实现；~qa=统一质量审查/验证/修复/收尾；~plan=结构化规划；~prd=重型规格；~auto=自动选择并继续执行后续阶段。',
+    '若判定为 T3，默认先走 ~plan / ~prd；纯质量审查、验真或收尾请求才优先 ~qa。',
     `涉及 UI 任务时，设计决策优先级：当前活跃 plan / PRD → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → 已读取的 hello-ui 规则；同时所有 UI 任务都必须满足 UI 质量基线。`,
     projectStorageHint,
     workflowHint ? `项目状态：${workflowHint}` : '',

package/scripts/notify-route.mjs

@@ -22,7 +22,7 @@ function shouldBypassRoute(prompt) {
 
 function buildHelpExtraRules(skillName) {
   if (skillName !== 'help') return ''
-  return ' 这是 HelloAGENTS 的帮助命令，不是宿主 CLI 的内置帮助。仅显示 HelloAGENTS 的帮助和当前设置；优先使用当前会话上下文中已注入的“当前用户设置”、配置文件原始 JSON 或此前读取结果摘要，上下文不存在或缺少要展示的配置项时才读取一次 ~/.helloagents/helloagents.json；自动激活技能说明仅在全局模式或已初始化项目时生效。不要调用宿主 CLI 的帮助工具（如 cli_help 或 /help），不要使用子代理，不要读取项目文件；若受工作区限制无法读取配置，必须明确说明并按已知默认值或已注入设置展示。'
+  return ' 这是 HelloAGENTS 的帮助命令，不是宿主 CLI 的内置帮助。仅显示 HelloAGENTS 的帮助和当前设置；优先使用当前会话上下文中已注入的“当前用户设置”、配置文件原始 JSON 或此前读取结果摘要，上下文不存在或缺少要展示的配置项时才读取一次 ~/.helloagents/helloagents.json；自动激活技能说明仅在宿主全局模式或已初始化项目时生效。不要调用宿主 CLI 的帮助工具（如 cli_help 或 /help），不要使用子代理，不要读取项目文件；若受工作区限制无法读取配置，必须明确说明并按已知默认值或已注入设置展示。'
 }
 
 function routeExplicitCommand({

package/scripts/notify.mjs

@@ -41,7 +41,7 @@ const EVENT_NAME = {
   UserPromptSubmit: IS_GEMINI ? 'BeforeAgent' : 'UserPromptSubmit',
   PreCompact: IS_GEMINI ? 'BeforeAgent' : 'PreCompact',
 };
-const RALPH_LOOP_ROUTE_COMMANDS = new Set(['verify', 'loop']);
+const RALPH_LOOP_ROUTE_COMMANDS = new Set(['qa', 'loop']);
 const CODEX_HOOKS_FILE = join(homedir(), '.codex', 'hooks.json');
 const GATE_MODULE_LOADERS = {
   'turn-stop-gate': () => import('./turn-stop-gate.mjs'),
@@ -459,7 +459,7 @@ function cmdInject() {
   const cwd = payload.cwd || process.cwd();
   const settings = getSettings();
   const bootstrapFile = resolveBootstrapFile(cwd, settings, HOST);
-  const shouldEnsureProjectLocal = bootstrapFile === 'bootstrap.md' || source === 'resume' || source === 'compact';
+  const shouldEnsureProjectLocal = isProjectRuntimeActive(cwd);
 
   startReplaySession(cwd, {
     host: HOST,

package/scripts/plan-contract.mjs

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url'
 import { resolveProjectPlanDir } from './project-storage.mjs'
 
 export const PLAN_CONTRACT_FILE_NAME = 'contract.json'
-const VALID_VERIFY_MODES = new Set(['test-first', 'review-first'])
+const VALID_QA_MODES = new Set(['standard', 'deep'])
 const VALID_ADVISOR_SOURCES = new Set(['claude', 'codex', 'gemini'])
 
 function normalizeStringArray(values) {
@@ -14,9 +14,9 @@ function normalizeStringArray(values) {
     .filter(Boolean))]
 }
 
-function normalizeVerifyMode(value) {
+function normalizeQaMode(value) {
   const normalized = typeof value === 'string' ? value.trim().toLowerCase() : ''
-  return VALID_VERIFY_MODES.has(normalized) ? normalized : ''
+  return VALID_QA_MODES.has(normalized) ? normalized : ''
 }
 
 function normalizeUiStyleAdvisorContract(input = {}) {
@@ -88,12 +88,11 @@ export function readPlanContract(planDir) {
 
 export function normalizePlanContract(input = {}) {
   return {
-    version: 1,
+    version: 2,
     source: typeof input.source === 'string' && input.source.trim() ? input.source.trim() : 'manual',
     originCommand: typeof input.originCommand === 'string' ? input.originCommand.trim() : '',
-    verifyMode: normalizeVerifyMode(input.verifyMode),
-    reviewerFocus: normalizeStringArray(input.reviewerFocus),
-    testerFocus: normalizeStringArray(input.testerFocus),
+    qaMode: normalizeQaMode(input.qaMode),
+    qaFocus: normalizeStringArray(input.qaFocus),
     ui: normalizeUiContract(input.ui),
     advisor: normalizeAdvisorContract(input.advisor),
   }
@@ -128,14 +127,11 @@ export function getPlanContractIssues(contract = null) {
   const advisorRequirement = getAdvisorRequirement(normalized)
   const visualValidation = getVisualValidationRequirement(normalized)
   const issues = []
-  if (!normalizeVerifyMode(normalized.verifyMode)) {
-    issues.push('contract.json missing valid verifyMode')
+  if (!normalizeQaMode(normalized.qaMode)) {
+    issues.push('contract.json missing valid qaMode')
   }
-  if (normalizeStringArray(normalized.testerFocus).length === 0) {
-    issues.push('contract.json missing testerFocus')
-  }
-  if (normalizeVerifyMode(normalized.verifyMode) === 'review-first' && normalizeStringArray(normalized.reviewerFocus).length === 0) {
-    issues.push('contract.json missing reviewerFocus for review-first flow')
+  if (normalizeStringArray(normalized.qaFocus).length === 0) {
+    issues.push('contract.json missing qaFocus')
   }
   if (normalized.ui?.required && normalizeStringArray(normalized.ui.sourcePriority).length === 0) {
     issues.push('contract.json missing ui.sourcePriority')

package/scripts/project-session-cleanup.mjs

@@ -1,19 +1,18 @@
-import { existsSync, readdirSync, rmSync } from 'node:fs'
+import { existsSync, readdirSync, rmSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 
 import {
   ACTIVE_SESSION_FILE_NAME,
-  CAPSULE_FILE_NAME,
-  EVENTS_FILE_NAME,
-  PROJECT_ARTIFACTS_DIR_NAME,
   PROJECT_SESSIONS_DIR_NAME,
   getProjectActivationDir,
   getProjectRoot,
   readJsonFile,
   writeJsonFileAtomic,
 } from './runtime-scope.mjs'
+import { LONG_RUNNING_TTL_MS } from './runtime-ttl.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 {
@@ -33,29 +32,6 @@ function isDirectoryEmptyRecursive(dirPath) {
   })
 }
 
-function listFilesRecursive(dirPath) {
-  const entries = readdirSync(dirPath, { withFileTypes: true })
-  return entries.flatMap((entry) => {
-    const entryPath = join(dirPath, entry.name)
-    if (entry.isDirectory()) {
-      return listFilesRecursive(entryPath).map((child) => `${entry.name}/${child}`)
-    }
-    return entry.isFile() ? [entry.name] : []
-  })
-}
-
-function isRouteOnlySessionDir(sessionDir) {
-  if (existsSync(join(sessionDir, 'STATE.md'))) return false
-  const files = listFilesRecursive(sessionDir).map((file) => file.replace(/\\/g, '/'))
-  if (files.length === 0) return false
-  if (!files.includes(`${PROJECT_ARTIFACTS_DIR_NAME}/codex-native-stop.json`)) return false
-  return files.every((file) => [
-    CAPSULE_FILE_NAME,
-    EVENTS_FILE_NAME,
-    `${PROJECT_ARTIFACTS_DIR_NAME}/codex-native-stop.json`,
-  ].includes(file))
-}
-
 function shouldKeepSession(active, workspace, session) {
   const activeWorkspace = active.workspace || active.branch || ''
   return activeWorkspace === workspace && active.session === session
@@ -75,7 +51,35 @@ function writeCleanupCheckpoint(activePath, active, now) {
   })
 }
 
-export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs = 0 } = {}) {
+function hasStateSnapshot(sessionDir) {
+  return existsSync(join(sessionDir, 'STATE.md'))
+}
+
+function readSessionStateMtimeMs(sessionDir) {
+  try {
+    return statSync(join(sessionDir, 'STATE.md')).mtimeMs
+  } catch {
+    return 0
+  }
+}
+
+function isStaleStateSession(sessionDir, now, maxAgeMs) {
+  const mtimeMs = readSessionStateMtimeMs(sessionDir)
+  return !Number.isFinite(mtimeMs) || mtimeMs <= 0 || (now - mtimeMs > maxAgeMs)
+}
+
+function isTransientSessionTemp(entryName = '') {
+  return /^\.[0-9]+-[0-9a-f-]+\.tmp$/i.test(entryName)
+}
+
+function cleanupTransientSessionTemps(sessionsDir, result) {
+  for (const entry of readdirSync(sessionsDir, { withFileTypes: true })) {
+    if (!entry.isFile() || !isTransientSessionTemp(entry.name)) continue
+    removePath(join(sessionsDir, entry.name), result, 'removedTempFiles')
+  }
+}
+
+export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs = 0, maxAgeMs = PROJECT_SESSION_MAX_AGE_MS } = {}) {
   const projectRoot = getProjectRoot(cwd)
   const activationDir = getProjectActivationDir(projectRoot)
   const sessionsDir = join(activationDir, PROJECT_SESSIONS_DIR_NAME)
@@ -84,7 +88,9 @@ export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs =
   const result = {
     sessionsDir,
     removedEmptyDirs: [],
-    removedRouteOnlyDirs: [],
+    removedInactiveDirs: [],
+    removedNoStateDirs: [],
+    removedTempFiles: [],
     errors: [],
     skipped: false,
   }
@@ -98,6 +104,12 @@ export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs =
     }
   }
 
+  try {
+    cleanupTransientSessionTemps(sessionsDir, result)
+  } catch (error) {
+    result.errors.push(`${sessionsDir}: ${error.message}`)
+  }
+
   for (const workspaceEntry of readdirSync(sessionsDir, { withFileTypes: true })) {
     if (!workspaceEntry.isDirectory()) continue
     const workspaceDir = join(sessionsDir, workspaceEntry.name)
@@ -110,8 +122,10 @@ export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs =
       try {
         if (isDirectoryEmptyRecursive(sessionDir)) {
           removePath(sessionDir, result, 'removedEmptyDirs')
-        } else if (isRouteOnlySessionDir(sessionDir)) {
-          removePath(sessionDir, result, 'removedRouteOnlyDirs')
+        } else if (!hasStateSnapshot(sessionDir)) {
+          removePath(sessionDir, result, 'removedNoStateDirs')
+        } else if (isStaleStateSession(sessionDir, now, maxAgeMs)) {
+          removePath(sessionDir, result, 'removedInactiveDirs')
         }
       } catch (error) {
         result.errors.push(`${sessionDir}: ${error.message}`)