qlogicagent 2.17.8 → 2.17.10

package/dist/types/protocol/wire/notification-payloads.d.ts

@@ -284,6 +284,20 @@ export interface TurnExecProgressNotification {
     totalLines: number;
     totalBytes: number;
 }
+/**
+ * Throttled long-turn progress (IM channel feedback). Emitted at most once per throttle
+ * interval while a turn keeps running tools; gateway/IM bridge renders it as a short
+ * progress line. Desktop UIs already show the tool stream and may ignore it.
+ */
+export interface TurnProgressNotification {
+    turnId: string;
+    /** Milliseconds since the turn started. */
+    elapsedMs: number;
+    /** Tool results observed so far this turn. */
+    toolCalls: number;
+    /** Name of the most recently completed tool. */
+    lastTool: string;
+}
 /** Generic progress heartbeat. */
 export interface TurnHeartbeatNotification {
     turnId: string;
@@ -466,6 +480,16 @@ export interface MemoryDecayCompletedNotification {
     archived: number;
     durationMs: number;
 }
+/** L3 启动扫描发现的待恢复会话（崩溃残留的 in-flight turn，session-lifecycle-recovery）。 */
+export interface SessionRecoveryPendingNotification {
+    sessions: Array<{
+        sessionId: string;
+        turnId: string;
+        startedAt: string;
+        lastUserPreview?: string;
+        hadSideEffectTool: boolean;
+    }>;
+}
 /** Session metadata changed. */
 export interface SessionInfoNotification {
     sessionId: string;
@@ -1002,6 +1026,7 @@ export interface NotificationMethodMap {
     "turn.todos_updated": TurnTodosUpdatedNotification;
     "task.updated": TaskUpdatedNotification;
     "turn.exec_progress": TurnExecProgressNotification;
+    "turn.progress": TurnProgressNotification;
     "turn.heartbeat": TurnHeartbeatNotification;
     "turn.tool_use_summary": TurnToolUseSummaryNotification;
     "turn.tool_selection_policy": TurnToolSelectionPolicyNotification;
@@ -1018,6 +1043,7 @@ export interface NotificationMethodMap {
     "memory.decay.completed": MemoryDecayCompletedNotification;
     "skills.updated": SkillsUpdatedNotification;
     "session.info": SessionInfoNotification;
+    "session.recovery_pending": SessionRecoveryPendingNotification;
     "permission.rule_updated": PermissionRuleUpdatedNotification;
     "team.member.notification": TeamMemberNotification;
     "turn.usage_update": TurnUsageUpdateNotification;

package/dist/types/runtime/execution/turn-progress-notifier.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 长任务进度通知（IM 渠道体验）：IM 里看不到工具流，超过 minIntervalMs 的轮次
+ * 以节流方式发 turn.progress，由 gateway/IM 桥接渲染成一条简短进度文本。
+ * 桌面端 UI 已有工具流展示，gateway 可按渠道选择忽略此通知。
+ */
+export interface TurnProgressNotifierOptions {
+    turnId: string;
+    send: (method: string, params: Record<string, unknown>) => void;
+    /** 两条进度通知的最小间隔；默认 10s。 */
+    minIntervalMs?: number;
+    now?: () => number;
+}
+export interface TurnProgressNotifier {
+    onToolResult(toolName: string): void;
+}
+export declare function createTurnProgressNotifier(options: TurnProgressNotifierOptions): TurnProgressNotifier;

package/dist/types/runtime/infra/acp-detector.d.ts

@@ -165,7 +165,11 @@ export declare class AcpDetector {
      */
     scanAsync(force?: boolean): Promise<AgentDescriptor[]>;
     private runScanAsync;
-    /** Return cached results without IO. */
+    /**
+     * Return cached results without IO. 冷缓存时后台预热（scanAsync）并返回 []，
+     * 绝不在 RPC 路径上同步 scan —— 同步探测（11-18s+）会饿死单线程引擎循环
+     * （x/product.confirm 60s 超时的根因）。调用方按"稍后再查"处理空列表。
+     */
     list(): AgentDescriptor[];
     /** Clear the detection cache. */
     clearCache(): void;

package/dist/types/runtime/infra/agent-process.d.ts

@@ -160,6 +160,7 @@ export declare function applyExternalDescriptorEnv(env: Record<string, string>,
     env?: Record<string, string>;
     suppressEnvKeys?: string[];
 }): Record<string, string>;
+export declare function buildChildEnv(config: AgentProcessConfig): Record<string, string>;
 /**
  * Build LLM-related environment variables for an external ACP teammate.
  *

package/dist/types/runtime/infra/astraclaw-capabilities.d.ts

@@ -20,11 +20,11 @@ export declare function buildAstraClawCapabilitiesSystemPrompt(input: {
     mcpAvailable: boolean;
     availableToolNames?: Iterable<string>;
     currentEnvironment?: string;
-}): string | undefined;
+}): Promise<string | undefined>;
 export declare function buildAstraClawCapabilitiesPromptPreamble(input: {
     projectRoot: string;
     mcpAvailable: boolean;
     availableToolNames?: Iterable<string>;
     currentEnvironment?: string;
-}): string | undefined;
+}): Promise<string | undefined>;
 export declare function handleAstraClawCapabilityToolCall(input: AstraClawCapabilityToolInput): Promise<AstraClawCapabilityToolResult>;

package/dist/types/runtime/infra/builtin-skills-seed.d.ts

@@ -0,0 +1,31 @@
+export interface SeedBuiltinSkillsOptions {
+    /** Global skill store dir (getUserSkillsDir()). Each skill lands at <storeDir>/<name>/SKILL.md. */
+    storeDir: string;
+    /** Override the shipped builtin-skills source dir; defaults to the packaged skills/builtin. */
+    builtinDir?: string;
+}
+export interface SeedBuiltinSkillsResult {
+    /** Names of skills newly copied this run (empty when all already present or source missing). */
+    seeded: string[];
+}
+/**
+ * Locate the shipped skills/builtin directory from a module directory.
+ *
+ * The module dir differs by packaging mode — crucially, the production build is an esbuild
+ * BUNDLE: this module is inlined into dist/cli.js, so at runtime import.meta.url resolves to
+ * dist/cli.js itself, NOT dist/runtime/infra/... Probe candidates in order:
+ * 1. hereDir/skills/builtin           — bundle: hereDir = dist/ → dist/skills/builtin
+ *                                       (build.mjs copies skills/builtin there).
+ * 2. hereDir/../../skills/builtin     — unbundled dist module at dist/runtime/infra/.
+ * 3. hereDir/../../../skills/builtin  — dev/tsx/vitest: src/runtime/infra → repo-root skills/builtin.
+ * Returns the first candidate that exists, or undefined when none does (stripped-down build).
+ * Exported pure (hereDir in → path out) so tests can drive it against synthetic layouts.
+ */
+export declare function resolveBuiltinDirFrom(hereDir: string): string | undefined;
+/**
+ * Copy each builtin skill directory into the store only when its target does not yet exist.
+ * Idempotent: a second run with everything already present returns { seeded: [] }.
+ * Missing builtinDir is not an error — returns { seeded: [] } so a stripped-down build
+ * (or a local checkout without the assets) never blocks startup.
+ */
+export declare function seedBuiltinSkills(options: SeedBuiltinSkillsOptions): SeedBuiltinSkillsResult;

package/dist/types/runtime/infra/project-data-gc.d.ts

@@ -5,5 +5,11 @@
  * re-indexes it). Only a dir with NEITHER (truly corrupt/orphaned — crashed mid-create) is reclaimed.
  * This makes the registry non-load-bearing for recovery: a lost projects.json never causes data loss.
  * Also prunes stale deletion tombstones. NEVER touches live projects' data or the user's workspace.
+ *
+ * TRULY ASYNC (not just deferred): the iteration count grows with every project dir ever created on
+ * this machine (unbounded on a long-lived box). Following the AcpDetector.scanAsync convention, this
+ * uses fs/promises and awaits between each directory — every await yields the event loop, so an RPC
+ * that arrives mid-GC is dispatched between directories instead of waiting for the whole sweep. The
+ * keep/reclaim judgment is unchanged; only the sync fs calls became awaited yield points.
  */
-export declare function gcOrphanProjectData(): void;
+export declare function gcOrphanProjectData(): Promise<void>;

package/dist/types/runtime/infra/skill-resolver.d.ts

@@ -48,6 +48,17 @@ export interface SkillActivationContext {
 export declare function resolveSkills(projectRoot?: string, activation?: SkillActivationContext): ResolvedSkill[];
 /** Only the skills active in the given project (for the system-prompt skills catalog / resolution). */
 export declare function resolveActiveSkills(projectRoot?: string, activation?: SkillActivationContext): ResolvedSkill[];
+/**
+ * Async, NON-BLOCKING, cached twin of {@link resolveSkills} for the first-token hot path
+ * ({@link createAvailableSkillsSection}). Returns ALL store skills annotated with mute/active state,
+ * exactly like {@link resolveSkills}, but reads off the event loop and reuses cached parse results when
+ * the store is unchanged. The sync {@link resolveSkills} is deliberately left intact for other callers.
+ */
+export declare function resolveSkillsAsync(projectRoot?: string, activation?: SkillActivationContext): Promise<ResolvedSkill[]>;
+/** Async twin of {@link resolveActiveSkills}: only the skills active in the given project context. */
+export declare function resolveActiveSkillsAsync(projectRoot?: string, activation?: SkillActivationContext): Promise<ResolvedSkill[]>;
+/** Test-only: drop the async raw-skill cache so each test observes a cold read. */
+export declare function __clearSkillResolveCacheForTests(): void;
 /**
  * Resolve a single skill by name to its store paths, or null if not present.
  * Resolution honors only the global store (single source of truth) and ignores
@@ -57,3 +68,7 @@ export declare function resolveSkillPath(name: string): {
     baseDir: string;
     filePath: string;
 } | null;
+export declare function skillConditionsMatch(meta: {
+    requiredTools?: string[];
+    environments?: string[];
+}, activation: SkillActivationContext | undefined): boolean;

package/dist/types/runtime/prompt/environment-context.d.ts

@@ -17,11 +17,33 @@
 import { type SystemPromptSection } from "./system-prompt-sections.js";
 import type { TaskDomain } from "./task-domain.js";
 export type ShellType = "bash" | "powershell" | "zsh" | "cmd" | "fish" | "unknown";
+/**
+ * Structural snapshot of the shell provider that `exec()` actually drives.
+ *
+ * Defined LOCALLY (not imported from src/skills/tools/shell) on purpose: the
+ * runtime/prompt layer must not depend on the skills layer (architecture
+ * boundary). The CLI layer, which may import both, reads the real snapshot via
+ * `getActiveShellInfo()` and passes it in here; TS structural typing makes the
+ * shapes compatible without a cross-layer import.
+ */
+export interface ShellInfo {
+    type: "bash" | "powershell";
+    shellPath?: string;
+    psEdition?: "5.1" | "7+";
+    isGitBashOnWindows?: boolean;
+}
 /**
  * Create a system prompt section that provides environment context.
  * Memoized — computed once per session (environment doesn't change mid-session).
+ *
+ * @param cwdOverride  Working directory to report (defaults to process.cwd()).
+ * @param shellInfo    Real active-shell facts from the provider (via the CLI).
+ *                     When omitted, the `- Shell:` line and guidance fall back to
+ *                     `detectShellType()` (env-based guess). The shell identity is
+ *                     folded into the memoize key so a different shell doesn't
+ *                     serve a stale cached section for the same cwd.
  */
-export declare function createEnvironmentContextSection(cwdOverride?: string): SystemPromptSection;
+export declare function createEnvironmentContextSection(cwdOverride?: string, shellInfo?: ShellInfo): SystemPromptSection;
 /**
  * Create the task guidance system prompt section.
  * Domain-aware: selects appropriate guidance based on detected or overridden task domain.
@@ -52,7 +74,7 @@ export declare function createLanguageSection(language?: string): SystemPromptSe
  * makes installed skills actually auto-activate; without it active skills only sit behind the
  * skill_view tool as a passive catalog and never fire on their own.
  */
-export declare function createAvailableSkillsSection(cwdOverride?: string): SystemPromptSection;
+export declare function createAvailableSkillsSection(cwdOverride?: string, availableToolNames?: string[]): SystemPromptSection;
 /**
  * Detect the response language from the user's current-turn text so the strong
  * explicit-language branch of createLanguageSection actually fires.

package/dist/types/runtime/prompt/identity-section.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Harness-owned identity section — 每轮（含轻量聊天轮）注入，使身份/型号回答与
+ * 入口渠道无关。审计结论：正常轮此前没有任何身份 section，桌面端答 "我是 Claude"
+ * （模型训练身份在真空中浮现）、微信端答 "qlogicagent, qlogic 团队"（硬编码人设
+ * 锚点 + .qlogicagent 路径 token 引发的编造）。此 section 是两者的唯一事实来源。
+ */
+import { type SystemPromptSection } from "./system-prompt-sections.js";
+export interface IdentityInfo {
+    /** 产品名（运营可配置），缺省 QLogicAgent */
+    productName?: string;
+    /** 可选的品牌/构建方说明行（运营可配置） */
+    vendorLine?: string;
+    provider?: string;
+    /** 本轮解析出的真实模型 id */
+    model?: string;
+}
+export declare function createIdentitySection(info: IdentityInfo): SystemPromptSection;

package/dist/types/runtime/session/inbound-upload-persistence.d.ts

@@ -12,6 +12,12 @@
  * transport cache; only long-term persistence is skipped).
  */
 import type { ChatMessage } from "../../protocol/wire/index.js";
+export interface PersistedUpload {
+    url: string;
+    localPath?: string;
+}
+/** 同 persistInboundUploadUrl，但返回持久化后的本地绝对路径（供模型直接 read/exec）。 */
+export declare function persistInboundUploadUrlDetailed(url: string, projectId: string, sessionId: string): Promise<PersistedUpload>;
 /**
  * Persist a single inbound upload URL to projectData uploads and return the rewritten proxy URL.
  * Non-transport URLs (already-persisted, remote, file://) and any failure return the input unchanged.
@@ -22,3 +28,17 @@ export declare function persistInboundUploadUrl(url: string, projectId: string,
  * resumed history already carries persisted local URLs). Mutates and returns the message array.
  */
 export declare function persistInboundUploadsForTurn(messages: ChatMessage[], projectId: string | undefined, sessionId: string | undefined): Promise<ChatMessage[]>;
+/**
+ * 在任意模型可见文本中查找文档类传输 URL，落盘并追加本地路径注记。
+ * 供两条真实投递路径复用：gateway 烤进 user text 的清单，以及
+ * turn-handler 的 attachmentModelContext（拼接到 LLM 视图的附件上下文）。
+ */
+export declare function appendLocalDocumentNotesToText(text: string, projectId: string | undefined, sessionId: string | undefined): Promise<string>;
+/**
+ * 把最后一条用户消息文本里的文档类传输 URL 抓下来落盘，并在消息末尾追加本地
+ * 路径注记 —— 模型从"短命 URL"起步变成从"可 read/exec 的本地文件"起步。
+ * image/video/audio 已由 persistInboundUploadsForTurn 处理，这里只管文档。
+ * 仅覆盖清单被烤进 user text 的 gateway 及 legacy 会话；新版 turn 的文档引用
+ * 走 attachmentModelContext，由 turn-handler 调 appendLocalDocumentNotesToText。
+ */
+export declare function persistInboundDocumentRefsForTurn(messages: ChatMessage[], projectId: string | undefined, sessionId: string | undefined): Promise<ChatMessage[]>;

package/dist/types/runtime/session/session-recovery.d.ts

@@ -0,0 +1,58 @@
+export declare function isSideEffectTool(name: string): boolean;
+/** 取最后一条 user 消息的纯文本前若干字，供崩溃恢复 UI 提示（多模态/空则无预览）。 */
+export declare function extractLastUserPreview(messages: ReadonlyArray<{
+    role: string;
+    content: unknown;
+}>): string | undefined;
+/**
+ * turn 开始：写 in-flight 标记。fire-and-forget 语义 —— 绝不阻塞或抛错打断 turn。
+ * projectRoot 未解析（无项目上下文）时静默跳过。
+ */
+export declare function markTurnInflight(sessionId: string, projectRoot: string | undefined, turnId: string, messages: ReadonlyArray<{
+    role: string;
+    content: unknown;
+}>): Promise<void>;
+/**
+ * 首个副作用工具执行时置位 hadSideEffectTool（仅首次，避免每次工具调用写盘）。
+ * 安全档不据此自动续，仅用于 L4 的"继续可能重复"提示 + 为智能档铺路。
+ */
+export declare function markInflightSideEffect(sessionId: string, projectRoot: string | undefined): Promise<void>;
+/**
+ * turn 结束（finally 到达 = 有始有终，哪怕失败/用户中断）：清标记 + 中断计数归零。
+ * finally 未到达（进程被硬杀/崩溃）→ 标记残留，由 L3 启动扫描接住。
+ */
+export declare function clearTurnInflight(sessionId: string, projectRoot: string | undefined): Promise<void>;
+interface SessionMetaLocation {
+    sessionId: string;
+    metadataPath: string;
+}
+/**
+ * 遍历当前 owner profile 下所有 project 的所有 session 的 metadata.json 绝对路径。
+ * 直接扫 projectData/<projectId>/sessions/<sessionId>/ —— 用绝对路径，绕开 projectRoot↔projectId
+ * 解析歧义（未注册 project 的残留 session 也覆盖到）。L2 清标记 + L3 启动扫描共用。
+ */
+export declare function enumerateSessionMetadataFiles(): Promise<SessionMetaLocation[]>;
+/**
+ * L2 优雅关闭：清所有 session 残留的 in-flight 标记 + 中断计数归零。
+ * 优雅关闭 == 主动清标记 == hermes 的 .clean_shutdown 语义（更简、单一事实源）。
+ * 直接原子改写 metadata.json（不经 updateSessionMetadata 的 projectRoot 解析）。返回清理数。
+ */
+export declare function clearAllInflightMarkers(): Promise<number>;
+export interface CrashedTurnInfo {
+    sessionId: string;
+    turnId: string;
+    startedAt: string;
+    lastUserPreview?: string;
+    hadSideEffectTool: boolean;
+}
+/**
+ * L3 启动扫描：找崩溃残留的 in-flight 标记，处理双校验/熔断，返回待恢复列表。
+ * agent 每次 initialize 调用 —— gateway 重启 or agent respawn 都覆盖（标记本身是事实源）。
+ *
+ * - 双校验（借鉴 codex #12382，spec §7）：transcript 最后一条 assistant ts ≥ marker.startedAt →
+ *   该轮其实已完成、只是清标记那步没落盘 → 静默清、不误报。
+ * - 熔断：连续崩溃中断达 MAX_INTERRUPTED_RECOVERY → 放弃（清标记 + recoveryAbandonedAt + fail-loud）。
+ * - 否则：保留标记 + 递增中断计数，收进待恢复列表（交给 UI 让用户手动续）。
+ */
+export declare function scanForCrashedTurns(): Promise<CrashedTurnInfo[]>;
+export {};

package/dist/types/runtime/session/session-types.d.ts

@@ -2,6 +2,22 @@ import type { ChatMessage } from "../../protocol/wire/index.js";
 import type { TokenUsage } from "../../agent/types.js";
 import type { SessionUsageSnapshot } from "./session-state.js";
 export declare const SESSION_SCHEMA_VERSION = 1;
+/** 熔断阈值：连续崩溃中断达此次数后放弃自动恢复（对齐 hermes stuck-loop 的 3）。 */
+export declare const MAX_INTERRUPTED_RECOVERY = 3;
+/**
+ * 在飞轮次标记。turn 开始写入 SessionMetadata.inflightTurn，正常完成/用户主动中断时清除。
+ * 崩溃/非优雅退出时它残留在磁盘上 —— 这就是"上次这轮没跑完"的显式信号
+ * （对照 codex CLI 靠时间戳隐式推断、坏了要手动裁 JSONL，见 docs/session-lifecycle-recovery-spec.md §7）。
+ */
+export interface InflightTurnMarker {
+    turnId: string;
+    /** turn 开始时间（ISO）。启动扫描用它与 transcript 最后一条 assistant 消息的 ts 做双校验。 */
+    startedAt: string;
+    /** 最后一条 user 消息前若干字（UI 提示用，不含敏感全文）。 */
+    lastUserPreview?: string;
+    /** 该轮是否已执行过有副作用的工具（写文件/发消息/外部 API）。安全档不据此自动续，仅用于 UI"可能重复"提示 + 为智能档铺路。 */
+    hadSideEffectTool?: boolean;
+}
 export interface SessionMetadata {
     schemaVersion?: number;
     sessionId: string;
@@ -30,6 +46,12 @@ export interface SessionMetadata {
     groupPlatform?: string;
     totalInputTokens?: number;
     totalOutputTokens?: number;
+    /** 在飞轮次标记：存在即"上次这轮没跑完"（崩溃残留）。turn 开始写、正常完成/中断清。 */
+    inflightTurn?: InflightTurnMarker;
+    /** 连续崩溃中断计数；turn 正常完成清零；达 MAX_INTERRUPTED_RECOVERY 熔断放弃恢复。 */
+    interruptedTurnCount?: number;
+    /** 达熔断阈值放弃恢复的时间戳（UI 显示"多次中断已停止自动恢复"）。 */
+    recoveryAbandonedAt?: string;
 }
 export interface PersistedSession {
     metadata: SessionMetadata;

package/dist/types/skills/tools/exec-tool.d.ts

@@ -16,7 +16,7 @@ export declare const EXEC_TOOL_SCHEMA: {
     readonly properties: {
         readonly command: {
             readonly type: "string";
-            readonly description: "Shell command to execute in PowerShell." | "Shell command to execute in bash. Use Unix-style commands (ls, cat, mkdir -p, etc.).";
+            readonly description: "Shell command to execute in PowerShell. See the # Environment section for the active edition and path/syntax rules." | "Shell command to execute in bash. Use Unix-style commands (ls, cat, mkdir -p, etc.).";
         };
         readonly description: {
             readonly type: "string";

package/dist/types/skills/tools/shell/command-classification.d.ts

@@ -50,3 +50,4 @@ export declare function requiresDedicatedReadSearchTool(classification: CommandC
  * called for reads/searches now (directory listing is allowed via exec — see above).
  */
 export declare function dedicatedToolRedirectMessage(classification: CommandClassification): string;
+export declare function commandTargetsBinaryFile(command: string | null): boolean;

package/dist/types/skills/tools/shell/index.d.ts

@@ -1,5 +1,5 @@
-export type { ShellType, BuildCommandOpts, BuiltCommand, ShellProvider, } from "./shell-provider.js";
-export { isPowerShellToolEnabled, getDefaultShellType, generateCommandId, } from "./shell-provider.js";
+export type { ShellType, PowerShellEdition, ShellSelection, WindowsPowerShellResolution, WindowsPowerShellProbe, BuildCommandOpts, BuiltCommand, ShellProvider, } from "./shell-provider.js";
+export { isPowerShellToolEnabled, resolveShellSelection, resolveWindowsPowerShell, getDefaultShellType, generateCommandId, } from "./shell-provider.js";
 export { createBashProvider } from "./bash-provider.js";
 export type { BashProviderOptions } from "./bash-provider.js";
 export { createPowerShellProvider, encodePowerShellCommand, } from "./powershell-provider.js";
@@ -14,5 +14,5 @@ export type { ProgressCallback } from "./task-output.js";
 export type { ExecResult, ShellCommand } from "./shell-command.js";
 export { wrapSpawn, createAbortedCommand, createFailedCommand, } from "./shell-command.js";
 export { subprocessEnv } from "./subprocess-env.js";
-export { exec, getCwd, setCwd, initCwd, getOriginalCwd, setShellProvider, getShellProvider, } from "./shell-exec.js";
+export { exec, getCwd, setCwd, initCwd, getOriginalCwd, setShellProvider, getShellProvider, getActiveShellInfo, } from "./shell-exec.js";
 export type { ExecOptions } from "./shell-exec.js";

package/dist/types/skills/tools/shell/powershell-provider.d.ts

@@ -1,4 +1,4 @@
-import type { ShellProvider } from "./shell-provider.js";
+import type { ShellProvider, PowerShellEdition } from "./shell-provider.js";
 /**
  * Encode a PowerShell command as UTF-16LE Base64 for -EncodedCommand.
  * This avoids all quoting/escaping issues when passing complex commands
@@ -7,9 +7,14 @@ import type { ShellProvider } from "./shell-provider.js";
  * Ported directly from cc's `encodePowerShellCommand()`.
  */
 export declare function encodePowerShellCommand(psCommand: string): string;
+export interface PowerShellProviderOptions {
+    /** Which PowerShell edition `shellPath` is (5.1 vs 7+); surfaced as `psEdition`. */
+    edition?: PowerShellEdition;
+}
 /**
  * Create a PowerShell ShellProvider.
  *
- * @param shellPath Absolute path to pwsh.exe or powershell.exe
+ * @param shellPath Absolute path (or PATH-resolvable name) to pwsh.exe / powershell.exe
+ * @param options   Optional edition metadata (from `resolveWindowsPowerShell`)
  */
-export declare function createPowerShellProvider(shellPath: string): ShellProvider;
+export declare function createPowerShellProvider(shellPath: string, options?: PowerShellProviderOptions): ShellProvider;

package/dist/types/skills/tools/shell/shell-exec.d.ts

@@ -31,6 +31,24 @@ export declare function setShellProvider(provider: ShellProvider): void;
  * Get the current shell provider, or throw if not configured.
  */
 export declare function getShellProvider(): ShellProvider;
+/**
+ * Read-only snapshot of the active shell provider's identity, as plain data.
+ *
+ * Consumed by the prompt layer (via the CLI, which passes it in — the prompt
+ * layer must not import shell modules) to tailor environment guidance to the
+ * shell that `exec()` actually drives, instead of re-guessing from env vars.
+ *
+ * Returns `undefined` when no provider has been configured yet. This MUST NOT
+ * throw: prompt assembly can run before/without `setShellProvider()` (tests,
+ * lightweight turns), and a missing provider is a normal "fall back to
+ * detectShellType()" signal, not an error.
+ */
+export declare function getActiveShellInfo(): {
+    type: ShellType;
+    shellPath: string;
+    psEdition?: "5.1" | "7+";
+    isGitBashOnWindows?: boolean;
+} | undefined;
 /**
  * Execute a shell command using the configured provider.
  * Creates a new child process for each invocation.

package/dist/types/skills/tools/shell/shell-provider.d.ts

@@ -2,6 +2,13 @@
  * Discriminated shell type identifier.
  */
 export type ShellType = "bash" | "powershell";
+/**
+ * Which PowerShell edition the active provider drives.
+ *   "5.1" = Windows PowerShell (powershell.exe) — no `&&`/`||`, use `;`.
+ *   "7+"  = PowerShell 7 (pwsh)                 — `&&`/`||` supported.
+ * Consumed by prompt/guidance layers to tailor syntax advice.
+ */
+export type PowerShellEdition = "5.1" | "7+";
 /**
  * Options passed to `buildExecCommand`.
  */
@@ -45,19 +52,31 @@ export interface ShellProvider {
      * PowerShell: false (no POSIX process groups on Windows).
      */
     readonly detached: boolean;
+    /**
+     * For PowerShell providers: which edition the binary is (5.1 vs 7+).
+     * Undefined for bash. Read by prompt guidance to decide `&&` vs `;`.
+     */
+    readonly psEdition?: PowerShellEdition;
+    /**
+     * True when this is a bash provider running on Windows (Git Bash / MSYS).
+     * Undefined/false otherwise. Read by prompt guidance for path conventions.
+     */
+    readonly isGitBashOnWindows?: boolean;
     /**
      * Wrap a raw user command into a full shell command string.
      * Handles:
      *   - Environment snapshots / session env sourcing (bash)
-     *   - UTF-16LE EncodedCommand wrapping (PowerShell)
      *   - CWD tracking (`pwd -P > file` / `Get-Location | Out-File`)
      *   - stdin redirect for interactive commands (bash)
+     * Returns the UNENCODED script; PowerShell's UTF-16LE EncodedCommand wrapping
+     * happens in getSpawnArgs so the encode is applied exactly once.
      */
     buildExecCommand(command: string, opts: BuildCommandOpts): Promise<BuiltCommand>;
     /**
      * Return the argv array for `child_process.spawn()`.
      * E.g. bash → `['-c', commandString]`
-     *      PS   → `['-NoProfile', '-NonInteractive', '-Command', cmd]`
+     *      PS   → `['-NoProfile', '-NonInteractive', '-EncodedCommand', <utf16le-base64(commandString)>]`
+     * (`commandString` is the UNENCODED script; PS encodes it here, exactly once.)
      */
     getSpawnArgs(commandString: string): string[];
     /**
@@ -66,18 +85,61 @@ export interface ShellProvider {
      */
     getEnvironmentOverrides(command: string): Promise<Record<string, string>>;
 }
+/** High-level shell family selected for the current platform + env. */
+export type ShellSelection = "powershell" | "bash";
+/**
+ * Pure decision: given a platform + env, pick the shell family.
+ *
+ * Contract (the "flip default"):
+ *   - non-win32                       → bash (unchanged)
+ *   - win32, QLOGICAGENT_SHELL=bash   → bash (explicit opt-in Git Bash)
+ *   - win32, QLOGICAGENT_SHELL=powershell|pwsh → powershell
+ *   - win32, QLOGICAGENT_USE_POWERSHELL truthy (compat alias) → powershell
+ *   - win32, nothing set              → powershell  ← flipped default
+ *
+ * `QLOGICAGENT_SHELL` is the single three-state switch; the legacy
+ * `QLOGICAGENT_USE_POWERSHELL` truthy flag is kept as a compat alias but is
+ * overridden by an explicit `QLOGICAGENT_SHELL=bash`.
+ */
+export declare function resolveShellSelection(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): ShellSelection;
 /**
- * Check if PowerShell tool mode should be enabled.
+ * Check if PowerShell tool mode should be enabled for the live process.
  * Mirrors cc's `isPowerShellToolEnabled()`.
  *
- * On Windows: enabled when `QLOGICAGENT_USE_POWERSHELL` is truthy.
- * On non-Windows: always false.
+ * On Windows the default is now PowerShell (see `resolveShellSelection`);
+ * `QLOGICAGENT_SHELL=bash` opts back into Git Bash. On non-Windows: false.
  */
 export declare function isPowerShellToolEnabled(): boolean;
 /**
  * Default shell type for the current platform.
  */
 export declare function getDefaultShellType(): ShellType;
+/**
+ * Result of Windows PowerShell resolution: the binary to spawn plus which
+ * edition it is (so guidance can decide `&&` vs `;`).
+ */
+export interface WindowsPowerShellResolution {
+    shellPath: string;
+    psEdition: PowerShellEdition;
+}
+/**
+ * Injectable probes for `resolveWindowsPowerShell` (so it is unit-testable off
+ * a real Windows host). Defaults hit the real filesystem / PATH.
+ */
+export interface WindowsPowerShellProbe {
+    /** Whether a path exists on disk. */
+    exists(path: string): boolean;
+    /** Absolute path to `pwsh` on PATH, or null if not found. */
+    pwshOnPath(): string | null;
+}
+/**
+ * Resolve which PowerShell binary to drive on Windows.
+ *
+ * Order: explicit `QLOGICAGENT_POWERSHELL_PATH` → `pwsh` on PATH (PS7) →
+ * well-known pwsh install path (PS7) → `powershell.exe` (5.1, always present).
+ * The returned `psEdition` records which one was chosen.
+ */
+export declare function resolveWindowsPowerShell(env: NodeJS.ProcessEnv, probe: WindowsPowerShellProbe): WindowsPowerShellResolution;
 /**
  * Generate a short random hex ID for CWD temp file naming.
  * Matches cc's `Math.floor(Math.random() * 0x10000).toString(16)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qlogicagent",
-  "version": "2.17.8",
+  "version": "2.17.10",
   "description": "XiaozhiClaw Agent CLI — subprocess architecture (JSON-RPC over stdio)",
   "type": "module",
   "main": "dist/index.js",
@@ -69,6 +69,7 @@
     "build:search-svc": "node scripts/build-search-svc.mjs",
     "start": "node dist/cli.js",
     "test": "vitest run",
+    "test:replay": "vitest run benchmarks/transcript-replay",
     "check": "pnpm run check:encoding-corruption && tsc --noEmit && pnpm test && pnpm run check:architecture-boundaries && pnpm run check:provider-core-boundary && pnpm run check:provider-core-release-sync && pnpm run check:pet-core-boundary && pnpm run check:workspace-hygiene && pnpm run check:package-artifact",
     "test:watch": "vitest",
     "benchmark:hermes-superiority": "tsx benchmarks/hermes-superiority/runner.ts",
@@ -81,6 +82,7 @@
     "check:workspace-hygiene": "node scripts/check-workspace-hygiene.mjs",
     "check:workspace-hygiene:strict": "node scripts/check-workspace-hygiene.mjs --strict",
     "check:package-artifact": "npm run build && node scripts/check-package-artifact.mjs",
+    "corpus:export-feedback": "tsx scripts/export-feedback-corpus.ts",
     "redteam:community-desensitization": "tsx src/runtime/community/community-desensitization-red-team-cli.ts",
     "clean:workspace-hygiene": "node scripts/clean-workspace-hygiene.mjs",
     "release": "node scripts/release.mjs"
@@ -106,6 +108,7 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.15.0",
     "esbuild": "^0.28.0",
+    "javascript-obfuscator": "^5.4.3",
     "oxlint": "1.67.0",
     "tsx": "^4.19.0",
     "typescript": "^5.9.0",