helloagents 3.0.8-beta.1 → 3.0.9-beta.1

package/scripts/notify-source.mjs

@@ -1,42 +1,13 @@
 import { basename, normalize, resolve } from 'node:path'
 
+import { resolveSessionToken } from './session-token.mjs'
+
 const HOST_LABELS = {
   codex: 'Codex',
   claude: 'Claude Code',
   gemini: 'Gemini',
 }
 
-const PAYLOAD_SESSION_KEYS = [
-  'sessionId',
-  'session_id',
-  'session',
-  'conversationId',
-  'conversation_id',
-  'conversation',
-  'threadId',
-  'thread_id',
-  'thread',
-  'windowId',
-  'window_id',
-  'window',
-  'tabId',
-  'tab_id',
-  'tab',
-  'requestId',
-  'request_id',
-]
-
-const ENV_SESSION_KEYS = [
-  'HELLOAGENTS_NOTIFY_SESSION_ID',
-  'WT_SESSION',
-  'TERM_SESSION_ID',
-  'KITTY_WINDOW_ID',
-  'ALACRITTY_WINDOW_ID',
-  'WINDOWID',
-  'WEZTERM_PANE',
-  'TAB_ID',
-]
-
 function normalizePath(filePath = '') {
   if (!filePath) return ''
   try {
@@ -61,34 +32,6 @@ function resolveProjectLabel(cwd = '') {
   return label || normalized.replace(/\\/g, '/')
 }
 
-function sanitizeSessionToken(value = '') {
-  const raw = String(value).trim().replace(/^[#:\s]+/, '')
-  const segments = raw
-    .split(/[^a-zA-Z0-9]+/)
-    .filter(Boolean)
-  const cleaned = segments.length > 1
-    ? segments[segments.length - 1]
-    : raw.replace(/[^a-zA-Z0-9_-]/g, '')
-
-  if (!cleaned) return ''
-  if (/^\d+$/.test(cleaned)) return cleaned
-  return cleaned.slice(0, 8)
-}
-
-function resolveSessionToken(payload, env, ppid) {
-  for (const key of PAYLOAD_SESSION_KEYS) {
-    const value = sanitizeSessionToken(readStringCandidate(payload, key))
-    if (value) return value
-  }
-
-  for (const key of ENV_SESSION_KEYS) {
-    const value = sanitizeSessionToken(env?.[key] || '')
-    if (value) return value
-  }
-
-  return ppid ? String(ppid) : ''
-}
-
 export function resolveNotificationSource({
   host = '',
   cwd = '',
@@ -98,7 +41,7 @@ export function resolveNotificationSource({
 } = {}) {
   const hostLabel = HOST_LABELS[host] || 'Agent'
   const projectLabel = resolveProjectLabel(readStringCandidate(payload, 'cwd') || cwd)
-  const sessionToken = resolveSessionToken(payload, env, ppid)
+  const sessionToken = resolveSessionToken({ payload, env, ppid })
   const parts = [hostLabel]
 
   if (projectLabel) parts.push(projectLabel)

package/scripts/notify.mjs

@@ -115,11 +115,17 @@ function readCompletionText(payload = {}) {
     || '';
 }
 
-function shouldRunDeliveryGate(cwd, lastMsg) {
+function readMainTurnState(cwd) {
   const turnState = readTurnState(cwd);
-  if (turnState?.role === 'main') {
-    return turnState.kind === 'complete';
-  }
+  return turnState?.role === 'main' ? turnState : null;
+}
+
+function consumeMainTurnState(cwd, turnState) {
+  if (turnState?.role === 'main') clearTurnState(cwd);
+}
+
+function shouldProcessCloseout(turnState, lastMsg) {
+  if (turnState) return turnState.kind === 'complete';
   return claimsTaskComplete(lastMsg);
 }
 
@@ -202,6 +208,7 @@ function cmdInject() {
     pkgRoot: PKG_ROOT,
     host: HOST,
     cwd,
+    payload,
   });
   clearRouteContext();
   clearTurnState(cwd);
@@ -212,13 +219,17 @@ function cmdStop() {
   const payload = readStdinJson();
   const lastMsg = readCompletionText(payload);
   const cwd = payload.cwd || process.cwd();
+  const turnState = readMainTurnState(cwd);
+  const shouldProcess = shouldProcessCloseout(turnState, lastMsg);
   clearRouteContext();
-  if (runRalphLoop(payload)) {
+  if (shouldProcess && runRalphLoop(payload)) {
+    consumeMainTurnState(cwd, turnState);
     playSound('warning');
     desktopNotify('warning', buildNotifyExtra(payload));
     return;
   }
-  if (shouldRunDeliveryGate(cwd, lastMsg) && runDeliveryGate(payload)) {
+  if (shouldProcess && runDeliveryGate(payload)) {
+    consumeMainTurnState(cwd, turnState);
     playSound('warning');
     desktopNotify('warning', buildNotifyExtra(payload));
     return;
@@ -226,8 +237,11 @@ function cmdStop() {
 
   const settings = getSettings();
   const level = settings.notify_level ?? 0;
-  if (level === 2 || level === 3) playSound('complete');
-  if (level === 1 || level === 3) desktopNotify('complete', buildNotifyExtra(payload));
+  if (shouldProcess) {
+    if (level === 2 || level === 3) playSound('complete');
+    if (level === 1 || level === 3) desktopNotify('complete', buildNotifyExtra(payload));
+  }
+  consumeMainTurnState(cwd, turnState);
   emptySuppress();
 }
 
@@ -255,16 +269,22 @@ function cmdCodexNotify() {
   if (type !== 'agent-turn-complete') return;
 
   const cwd = data.cwd || process.cwd();
-  const turnState = readTurnState(cwd);
-  if (!turnState || turnState.role !== 'main') return;
+  const turnState = readMainTurnState(cwd);
+  if (!turnState) return;
+  if (turnState.kind !== 'complete') {
+    consumeMainTurnState(cwd, turnState);
+    return;
+  }
 
   const settings = getSettings();
-  if (turnState.kind === 'complete' && runRalphLoop({ cwd })) {
+  if (runRalphLoop(data)) {
+    consumeMainTurnState(cwd, turnState);
     playSound('warning');
     desktopNotify('warning', buildNotifyExtra(data));
     return;
   }
-  if (turnState.kind === 'complete' && runDeliveryGate({ cwd })) {
+  if (runDeliveryGate(data)) {
+    consumeMainTurnState(cwd, turnState);
     playSound('warning');
     desktopNotify('warning', buildNotifyExtra(data));
     return;
@@ -273,6 +293,7 @@ function cmdCodexNotify() {
   const level = settings.notify_level ?? 0;
   if (level === 2 || level === 3) playSound('complete');
   if (level === 1 || level === 3) desktopNotify('complete', buildNotifyExtra(data));
+  consumeMainTurnState(cwd, turnState);
 }
 
 const cmd = process.argv[2] || '';

package/scripts/project-storage.mjs

@@ -5,10 +5,13 @@ import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, normalize, resolve } from 'node:path'
 
 import { DEFAULTS } from './cli-config.mjs'
+import { resolveSessionToken } from './session-token.mjs'
 
 export const PROJECT_DIR_NAME = '.helloagents'
 const PROJECTS_DIR_NAME = 'projects'
+const PROJECT_SESSIONS_DIR_NAME = 'sessions'
 const PROJECT_STORE_MODES = new Set(['local', 'repo-shared'])
+const DEFAULT_STATE_SESSION_TOKEN = 'default'
 
 function safeJson(filePath) {
   try {
@@ -31,6 +34,19 @@ function runGitRevParse(cwd, args = []) {
   }
 }
 
+function runGitCommand(cwd, args = []) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf-8',
+      timeout: 5_000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+  } catch {
+    return ''
+  }
+}
+
 function resolveGitTopLevel(cwd) {
   const absolute = runGitRevParse(cwd, ['--path-format=absolute', '--show-toplevel'])
   if (absolute) return normalize(absolute)
@@ -54,6 +70,16 @@ function sanitizeRepoName(value = '') {
   return normalized || 'project'
 }
 
+function sanitizeStateScopeSegment(value = '', fallback = '') {
+  const normalized = String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48)
+  return normalized || fallback
+}
+
 function buildProjectKey(cwd) {
   const repoRoot = resolveGitTopLevel(cwd)
   const commonDir = resolveGitCommonDir(cwd, repoRoot)
@@ -87,6 +113,15 @@ function formatPromptPath(pathValue = '') {
   return pathValue ? normalize(pathValue).replace(/\\/g, '/') : ''
 }
 
+function resolveGitBranchName(cwd) {
+  const branchName = runGitRevParse(cwd, ['--abbrev-ref', 'HEAD'])
+  if (branchName && branchName !== 'HEAD') return branchName
+
+  const symbolicBranchName = runGitCommand(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD'])
+  if (symbolicBranchName && symbolicBranchName !== 'HEAD') return symbolicBranchName
+  return ''
+}
+
 export function normalizeProjectStoreMode(value) {
   const normalized = typeof value === 'string' ? value.trim().toLowerCase() : ''
   return PROJECT_STORE_MODES.has(normalized) ? normalized : DEFAULTS.project_store_mode
@@ -105,8 +140,38 @@ export function getProjectActivationDir(cwd) {
   return join(cwd, PROJECT_DIR_NAME)
 }
 
-export function getProjectStatePath(cwd) {
-  return join(getProjectActivationDir(cwd), 'STATE.md')
+export function getProjectSessionStateScope(cwd, {
+  payload = {},
+  env = process.env,
+  ppid = process.ppid,
+} = {}) {
+  const rawSessionToken = resolveSessionToken({
+    payload,
+    env,
+    ppid,
+    allowPpidFallback: false,
+  })
+  const branchName = sanitizeStateScopeSegment(resolveGitBranchName(cwd), 'detached')
+  const sessionToken = sanitizeStateScopeSegment(rawSessionToken, DEFAULT_STATE_SESSION_TOKEN)
+  const sessionDir = join(
+    getProjectActivationDir(cwd),
+    PROJECT_SESSIONS_DIR_NAME,
+    branchName,
+    sessionToken,
+  )
+
+  return {
+    stateScope: 'session',
+    stateSessionToken: sessionToken,
+    stateSessionMode: rawSessionToken ? 'host-session' : 'default',
+    stateBranch: branchName,
+    sessionDir,
+    statePath: join(sessionDir, 'STATE.md'),
+  }
+}
+
+export function getProjectStatePath(cwd, options = {}) {
+  return getProjectSessionStateScope(cwd, options).statePath
 }
 
 export function isRepoSharedProjectStore(cwd) {
@@ -122,10 +187,10 @@ export function getProjectStoreDir(cwd) {
   return join(homedir(), PROJECT_DIR_NAME, PROJECTS_DIR_NAME, projectKey.key)
 }
 
-export function getProjectStoreSummary(cwd) {
+export function getProjectStoreSummary(cwd, options = {}) {
   const activationDir = getProjectActivationDir(cwd)
   const storeDir = getProjectStoreDir(cwd)
-  const statePath = getProjectStatePath(cwd)
+  const stateScope = getProjectSessionStateScope(cwd, options)
   const projectKey = buildProjectKey(cwd)
   const projectStoreMode = getProjectStoreMode(cwd)
 
@@ -133,14 +198,20 @@ export function getProjectStoreSummary(cwd) {
     projectStoreMode,
     activationDir,
     storeDir,
-    statePath,
+    statePath: stateScope.statePath,
+    stateScope: stateScope.stateScope,
+    stateSessionToken: stateScope.stateSessionToken,
+    stateSessionMode: stateScope.stateSessionMode,
+    stateBranch: stateScope.stateBranch,
+    sessionStateDir: stateScope.sessionDir,
     usesSharedStore: projectStoreMode === 'repo-shared',
     projectKey: projectKey.key,
     repoRoot: projectKey.repoRoot,
     commonDir: projectKey.commonDir,
     promptActivationDir: formatPromptPath(activationDir),
     promptStoreDir: formatPromptPath(storeDir),
-    promptStatePath: formatPromptPath(statePath),
+    promptStatePath: formatPromptPath(stateScope.statePath),
+    promptSessionStateDir: formatPromptPath(stateScope.sessionDir),
   }
 }
 
@@ -203,14 +274,21 @@ export function describeProjectStoreFile(cwd, relativePath = '') {
   return `逻辑路径 \`${logicalPath}\`（实际存储：\`${actualPath}\`）`
 }
 
-export function buildProjectStorageHint(cwd) {
-  const summary = getProjectStoreSummary(cwd)
-  if (!summary.usesSharedStore) return ''
-  return `项目存储：\`project_store_mode=repo-shared\`；本地激活/运行态目录仍是 \`${summary.promptActivationDir}\`，知识库/方案目录改为 \`${summary.promptStoreDir}\`。`
+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}\``)
+  }
+  return hints.join('。') + (hints.length > 0 ? '。' : '')
 }
 
-export function buildProjectStorageBlock(cwd) {
-  const summary = getProjectStoreSummary(cwd)
+export function buildProjectStorageBlock(cwd, options = {}) {
+  const summary = getProjectStoreSummary(cwd, options)
   if (!summary.usesSharedStore && !existsSync(summary.activationDir)) {
     return ''
   }
@@ -218,18 +296,32 @@ export function buildProjectStorageBlock(cwd) {
   const details = {
     project_store_mode: summary.projectStoreMode,
     activation_dir: summary.promptActivationDir,
+    state_scope: summary.stateScope,
     state_path: summary.promptStatePath,
+    state_branch: summary.stateBranch,
+    state_session_token: summary.stateSessionToken,
+    state_session_mode: summary.stateSessionMode,
+    session_state_dir: summary.promptSessionStateDir,
     knowledge_base_dir: summary.promptStoreDir,
     uses_shared_store: summary.usesSharedStore,
   }
 
+  const explanations = []
+  explanations.push('说明：恢复快照只认 `state_path` 这一个权威路径，不再读写旧的项目级 `.helloagents/STATE.md`。')
+  if (summary.stateSessionMode === 'default') {
+    explanations.push('说明：当前宿主未提供稳定会话标识，因此自动使用分支级默认会话槽位，仍保持新目录结构。')
+  }
+  if (summary.usesSharedStore) {
+    explanations.push('说明：`STATE.md` 与 `.ralph-*.json` 继续写本地激活目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。')
+  } else {
+    explanations.push('说明：当前使用项目本地 `.helloagents/` 作为激活目录、知识库目录和方案目录。')
+  }
+
   return [
     '## 当前项目存储',
     '```json',
     JSON.stringify(details, null, 2),
     '```',
-    summary.usesSharedStore
-      ? '说明：`STATE.md` 与 `.ralph-*.json` 继续写本地激活目录；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 写知识库/方案目录。'
-      : '说明：当前使用项目本地 `.helloagents/` 作为激活目录、知识库目录和方案目录。',
+    ...explanations,
   ].join('\n')
 }

package/scripts/session-token.mjs

@@ -0,0 +1,73 @@
+const PAYLOAD_SESSION_KEYS = [
+  'sessionId',
+  'session_id',
+  'session',
+  'conversationId',
+  'conversation_id',
+  'conversation',
+  'threadId',
+  'thread_id',
+  'thread',
+  'windowId',
+  'window_id',
+  'window',
+  'tabId',
+  'tab_id',
+  'tab',
+  'requestId',
+  'request_id',
+]
+
+const ENV_SESSION_KEYS = [
+  'HELLOAGENTS_NOTIFY_SESSION_ID',
+  'WT_SESSION',
+  'TERM_SESSION_ID',
+  'KITTY_WINDOW_ID',
+  'ALACRITTY_WINDOW_ID',
+  'WINDOWID',
+  'WEZTERM_PANE',
+  'TAB_ID',
+]
+
+function readStringCandidate(input, key) {
+  if (!input || typeof input !== 'object') return ''
+  const value = input[key]
+  if (typeof value === 'string') return value.trim()
+  if (typeof value === 'number') return String(value)
+  return ''
+}
+
+export function sanitizeSessionToken(value = '') {
+  const raw = String(value).trim().replace(/^[#:\s]+/, '')
+  const segments = raw
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+  const cleaned = segments.length > 1
+    ? segments[segments.length - 1]
+    : raw.replace(/[^a-zA-Z0-9_-]/g, '')
+
+  if (!cleaned) return ''
+  if (/^\d+$/.test(cleaned)) return cleaned
+  return cleaned.slice(0, 8)
+}
+
+export function resolveSessionToken({
+  payload = {},
+  env = process.env,
+  ppid = process.ppid,
+  allowPpidFallback = true,
+} = {}) {
+  for (const key of PAYLOAD_SESSION_KEYS) {
+    const value = sanitizeSessionToken(readStringCandidate(payload, key))
+    if (value) return value
+  }
+
+  for (const key of ENV_SESSION_KEYS) {
+    const value = sanitizeSessionToken(env?.[key] || '')
+    if (value) return value
+  }
+
+  return allowPpidFallback && ppid ? String(ppid) : ''
+}
+
+export { ENV_SESSION_KEYS, PAYLOAD_SESSION_KEYS }

package/scripts/workflow-core.mjs

@@ -13,6 +13,13 @@ import { describeProjectStoreFile, getProjectDesignContractPath } from './projec
 export function getTargetPlans(snapshot) {
   return snapshot.activePlans.length > 0 ? snapshot.activePlans : snapshot.plans
 }
+
+function describeStateLabel(state) {
+  if (state.stateSessionMode === 'default') {
+    return '当前分支默认会话槽位的 `STATE.md`'
+  }
+  return '当前会话的 `STATE.md`'
+}
 export function classifyPlan(plan) {
   if (!plan) {
     return {
@@ -97,27 +104,28 @@ function collectStateSyncIssues(snapshot) {
   const issues = []
   const hasPlans = snapshot.plans.length > 0
   const state = snapshot.state
+  const stateLabel = describeStateLabel(state)
 
   if (!hasPlans) {
     return issues
   }
 
   if (!state.exists) {
-    issues.push('当前已存在方案包，但 `.helloagents/STATE.md` 缺失')
+    issues.push(`当前已存在方案包，但${stateLabel} 缺失`)
     return issues
   }
 
   if (!state.referencedPlanDir) {
-    issues.push('当前已存在方案包，但 `STATE.md` 未记录活跃方案路径')
+    issues.push(`${stateLabel} 未记录活跃方案路径`)
   }
   if (!state.sections['主线目标']) {
-    issues.push('`STATE.md` 缺少“主线目标”')
+    issues.push(`${stateLabel} 缺少“主线目标”`)
   }
   if (!state.sections['正在做什么']) {
-    issues.push('`STATE.md` 缺少“正在做什么”')
+    issues.push(`${stateLabel} 缺少“正在做什么”`)
   }
   if (!state.sections['下一步']) {
-    issues.push('`STATE.md` 缺少“下一步”')
+    issues.push(`${stateLabel} 缺少“下一步”`)
   }
 
   return issues
@@ -137,7 +145,7 @@ export function buildStateSyncHintFromSnapshot(snapshot) {
 
 export function buildStateRoleHintFromSnapshot(snapshot) {
   if (!snapshot.state.exists || snapshot.plans.length > 0) return ''
-  return '恢复约束：当前仅检测到 `.helloagents/STATE.md`；先以当前用户消息、显式命令和代码事实确认主线，STATE.md 只用于找回上次停在哪，不是当前任务的自动授权或唯一判断依据。'
+  return `恢复约束：当前仅检测到${describeStateLabel(snapshot.state)}；先以当前用户消息、显式命令和代码事实确认主线，STATE.md 只用于找回上次停在哪，不是当前任务的自动授权或唯一判断依据。`
 }
 
 export function buildUiContractHint(cwd, snapshot) {

package/scripts/workflow-plan-files.mjs

@@ -2,7 +2,11 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { isAbsolute, join, normalize } from 'node:path'
 
 import { getPlanContractIssues, readPlanContract } from './plan-contract.mjs'
-import { getProjectPlansDir, getProjectStatePath, resolveProjectPlanDir } from './project-storage.mjs'
+import {
+  getProjectPlansDir,
+  getProjectSessionStateScope,
+  resolveProjectPlanDir,
+} from './project-storage.mjs'
 
 const PLAN_TEMPLATE_MARKERS = {
   'requirements.md': [
@@ -170,15 +174,22 @@ function comparePlanEntries(a, b) {
   return a.planName.localeCompare(b.planName)
 }
 
-export function readStateSnapshot(cwd) {
-  const statePath = getProjectStatePath(cwd)
+export function readStateSnapshot(cwd, options = {}) {
+  const stateScope = getProjectSessionStateScope(cwd, options)
+  const statePath = stateScope.statePath
+  const exists = existsSync(statePath)
   const content = readText(statePath)
   const sections = parseMarkdownSections(content)
   const referencedPlanDir = resolvePlanDir(cwd, sections['方案'])
 
   return {
     statePath,
-    exists: existsSync(statePath),
+    stateScope: stateScope.stateScope,
+    stateSessionToken: stateScope.stateSessionToken,
+    stateSessionMode: stateScope.stateSessionMode,
+    stateBranch: stateScope.stateBranch,
+    sessionScoped: stateScope.stateScope === 'session',
+    exists,
     content,
     sections,
     referencedPlanDir,
@@ -230,8 +241,8 @@ export function listPlanPackages(cwd) {
     .sort(comparePlanEntries)
 }
 
-export function getWorkflowSnapshot(cwd) {
-  const state = readStateSnapshot(cwd)
+export function getWorkflowSnapshot(cwd, options = {}) {
+  const state = readStateSnapshot(cwd, options)
   const plans = listPlanPackages(cwd).map((entry) => ({
     ...entry,
     referencedByState: state.referencedPlanDir ? normalize(entry.dirPath) === normalize(state.referencedPlanDir) : false,

package/scripts/workflow-state.mjs

@@ -16,27 +16,27 @@ import {
   buildRecommendation,
 } from './workflow-recommendation.mjs'
 
-export function getDeliveryAction(cwd) {
-  const snapshot = getWorkflowSnapshot(cwd)
+export function getDeliveryAction(cwd, options = {}) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
   const recommendation = buildRecommendation(snapshot, cwd)
   return buildDeliveryActionFromSnapshot(snapshot, cwd, recommendation)
 }
 
-export function getWorkflowRecommendation(cwd) {
-  return buildRecommendation(getWorkflowSnapshot(cwd), cwd)
+export function getWorkflowRecommendation(cwd, options = {}) {
+  return buildRecommendation(getWorkflowSnapshot(cwd, options), cwd)
 }
 
-export function buildStateSyncHint(cwd) {
-  return buildStateSyncHintFromSnapshot(getWorkflowSnapshot(cwd))
+export function buildStateSyncHint(cwd, options = {}) {
+  return buildStateSyncHintFromSnapshot(getWorkflowSnapshot(cwd, options))
 }
 
-export function buildDeliveryGateHint(cwd) {
-  const snapshot = getWorkflowSnapshot(cwd)
+export function buildDeliveryGateHint(cwd, options = {}) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
   return buildDeliveryGateHintFromSnapshot(snapshot, cwd, buildRecommendation(snapshot, cwd))
 }
 
-export function buildWorkflowRouteHint(cwd) {
-  const snapshot = getWorkflowSnapshot(cwd)
+export function buildWorkflowRouteHint(cwd, options = {}) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
   const recommendation = buildRecommendation(snapshot, cwd)
   const stateSyncHint = buildStateSyncHintFromSnapshot(snapshot)
   const stateRoleHint = buildStateRoleHintFromSnapshot(snapshot)
@@ -87,8 +87,8 @@ function buildCommandRouteMessage(skillName, recommendation, verifyModeHint) {
   return `当前工作流约束：${recommendation.summary} 当前建议下一命令：~${recommendation.nextCommand}。${recommendation.guidance}`
 }
 
-export function buildCommandRouteHint(skillName, cwd) {
-  const snapshot = getWorkflowSnapshot(cwd)
+export function buildCommandRouteHint(skillName, cwd, options = {}) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
   const recommendation = buildRecommendation(snapshot, cwd)
   const contextHints = [
     buildStateRoleHintFromSnapshot(snapshot),

package/skills/commands/build/SKILL.md

@@ -8,7 +8,7 @@ Trigger: ~build [description]
 
 `~build` 是执行实现命令。它负责读取现有需求、方案包与项目上下文，完成实现、局部验证、修复循环，并把结果衔接到后续验证与收尾。
 执行 `~build` 时，通用阶段边界按当前已加载 bootstrap 执行；本 skill 负责补充实现前定位、实现约束，以及进入 `~verify` / 收尾前的实现边界。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md`、`verify.yaml` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 与 `.ralph-*.json` 保持项目本地；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，知识库、`DESIGN.md`、`verify.yaml` 与方案包按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 铁律
 - 默认先定位上下文与范围，再修改代码
@@ -20,7 +20,7 @@ Trigger: ~build [description]
 
 ### 1. 恢复与定位
 
-- 优先按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”恢复当前链路；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先读取 `.helloagents/STATE.md` 作为恢复快照，再用当前用户消息、活跃方案包 / PRD 与代码事实校正主线
+- 优先按当前已加载 bootstrap 的“.helloagents/ 文件读取优先级”恢复当前链路；若当前消息显式继续既有链路，或会话刚经历恢复 / 压缩，先读取 `.helloagents/STATE.md` 作为恢复快照（若当前项目存储给出 `state_path`，则优先读取该当前会话的 `STATE.md`），再用当前用户消息、活跃方案包 / PRD 与代码事实校正主线
 - 若存在最近的活跃方案包，读取对应的：
   - `requirements.md`
   - `plan.md`

package/skills/commands/clean/SKILL.md

@@ -7,7 +7,7 @@ policy:
 Trigger: ~clean
 
 执行 `~clean` 时，方案包归档、临时文件清理和 `STATE.md` 更新边界按当前已加载 bootstrap 执行；本命令只负责判定哪些方案包可以清理，以及输出清理摘要。
-`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 和临时运行态文件保持项目本地；若 `project_store_mode=repo-shared`，`plans/` 与 `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
+`.helloagents/` 在本 skill 中统一按项目级存储路径理解：`STATE.md` 和临时运行态文件保持项目本地；若当前上下文中的“当前项目存储”给出 `state_path`，本轮恢复快照统一读写该路径；若 `project_store_mode=repo-shared`，`plans/` 与 `archive/` 按当前上下文中已注入的项目知识/方案目录解析。
 
 ## 流程
 

package/skills/commands/commit/SKILL.md

@@ -20,7 +20,7 @@ Trigger: ~commit [message]
    - ""（空，默认）→ 不添加归属
    - 有内容（如 "Co-Authored-By: HelloAGENTS"）→ 添加该内容到 commit message
 6. 执行 git commit
-7. 若项目已有 `.helloagents/STATE.md`，按 bootstrap 的“已有则更新”规则同步当前已提交状态
+7. 若当前 `STATE.md` 已存在（优先取当前项目存储中的 `state_path`，未注入时回退 `.helloagents/STATE.md`），按 bootstrap 的“已有则更新”规则同步当前已提交状态
 
 ## 知识库同步
 提交后，继续复用上方已解析的同一份设置获取 `kb_create_mode`，不要再次读取 `~/.helloagents/helloagents.json`：

package/skills/commands/idea/SKILL.md

@@ -11,7 +11,7 @@ Trigger: ~idea [description]
 ## 铁律
 - 只讨论，不编写实现代码，不创建项目文件，不执行实现操作
 - 不创建 `.helloagents/`
-- 不创建或更新 `.helloagents/STATE.md`、知识库文件、方案包或项目级规则文件
+- 不创建或更新 `.helloagents/STATE.md`；若当前项目存储给出 `state_path`，同样禁止更新该当前 `STATE.md`、知识库文件、方案包或项目级规则文件
 - 不生成方案包
 - 不执行会改变工作区或外部状态的命令
 - 不默认使用子代理