qlogicagent 2.17.9 → 2.18.1

package/dist/types/runtime/infra/model-registry.d.ts

@@ -29,6 +29,13 @@ export interface ModelEntry {
     routeIntents: ModelPurpose[];
     baseUrl?: string;
     enabled: boolean;
+    /**
+     * Purposes this model has been individually turned OFF for. Absent/empty = on for all of its
+     * routeIntents (still subject to the master `enabled`). Lets one model serve several purposes
+     * with independent on/off switches, so disabling it under one purpose group never strands the
+     * bindings that use it for another.
+     */
+    disabledPurposes?: ModelPurpose[];
     nativeModelId?: string;
     transport?: string;
     contextWindow?: number;
@@ -40,6 +47,11 @@ export interface ModelEntry {
     pricing?: Record<string, unknown>;
     /** Thinking-strength control class for the UI (see ReasoningMode). */
     reasoningMode?: ReasoningMode;
+    /**
+     * 归一后的「服务端推荐默认用途」(来自 capabilityProfile.default_for)。零配置默认绑定优先选
+     * defaultForIntents 命中本用途的模型,读不到则回退硬编码偏好。空/缺 → 无服务端推荐。
+     */
+    defaultForIntents?: ModelPurpose[];
 }
 export interface ModelCapabilityProfile {
     tasks?: string[];
@@ -55,6 +67,12 @@ export interface ModelCapabilityProfile {
         requires_confirmation?: boolean;
         default_selectable?: boolean;
     };
+    /**
+     * 服务端声明:该模型是这些 route_intent 的「推荐默认」(零配置绑定优先读它)。原始 intent 字符串
+     * (由 llmrouter 归一为规范名);客户端过滤到已知 ModelPurpose 得 defaultForIntents。空/缺 → 无服务端
+     * 推荐 → 客户端回退硬编码偏好(向后兼容:llmrouter 未部署 default_for 时行为与现状完全一致)。
+     */
+    default_for?: string[];
 }
 export type PurposeBindings = Partial<Record<ModelPurpose, string>>;
 export interface ModelRegistryConfig {
@@ -62,6 +80,7 @@ export interface ModelRegistryConfig {
     models: Array<{
         id: string;
         enabled?: boolean;
+        disabledPurposes?: ModelPurpose[];
     }>;
     bindings: PurposeBindings;
     tunables?: Record<string, unknown>;
@@ -84,6 +103,7 @@ export declare class ModelRegistry {
     private catalogProviders;
     private models;
     private modelEnabledOverrides;
+    private modelPurposeDisabled;
     private bindings;
     private injectedKeyStates;
     private settingsPath;
@@ -106,6 +126,12 @@ export declare class ModelRegistry {
      */
     acceptsInputModality(modality: string, purpose?: ModelPurpose): boolean;
     isAvailable(purpose: ModelPurpose): boolean;
+    /**
+     * Whether `id` is enabled for `purpose`. The master `enabled` flag is the global gate; on top of it
+     * a single purpose can be switched off (modelPurposeDisabled) without touching the model's other
+     * purposes. This is what keeps "disable in 文本生成" from stranding the 图像理解 binding.
+     */
+    isEnabledForPurpose(id: string, purpose: ModelPurpose): boolean;
     resolveModelForPurpose(purpose: ModelPurpose): string | null;
     addProvider(providerId: string, opts?: {
         baseUrl?: string;
@@ -132,8 +158,23 @@ export declare class ModelRegistry {
     replaceCatalogModels(entries: ModelEntry[]): void;
     replaceProviderModels(providerId: string, entries: ModelEntry[]): void;
     removeModel(id: string): void;
-    enableModel(id: string): void;
-    disableModel(id: string): void;
+    /**
+     * Enable a model. With `purpose`, enables it for just that purpose (clearing its per-purpose OFF
+     * switch); if the whole model was off, it flips on but keeps its OTHER purposes off so a single
+     * "turn on imageUnderstanding" never silently re-enables textGeneration too. Without `purpose`,
+     * enables the model globally (on for all of its purposes).
+     */
+    enableModel(id: string, purpose?: ModelPurpose): void;
+    /**
+     * Disable a model. With `purpose`, turns it off for just that purpose; the master flag only flips
+     * off once EVERY one of its routeIntents is off, so purpose-agnostic consumers (default-model
+     * pickers) still see the model while any purpose stays live. Without `purpose`, disables globally.
+     */
+    disableModel(id: string, purpose?: ModelPurpose): void;
+    private isMasterEnabled;
+    private setMasterEnabled;
+    private setPurposeDisabled;
+    private purposeDisabledArray;
     listModels(filter?: {
         purpose?: ModelPurpose;
         provider?: string;

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/infra/user-dirs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 跨平台获取用户常见目录(桌面/下载/文档)的真实绝对路径,供 environment-context 注入给 agent——
+ * 让「读桌面/下载的文件」这类桌面端最常见请求有一个确定的绝对路径锚点,而不是相对会话工作区瞎找。
+ *
+ * 各平台权威来源(都不能简单 homedir + "/Desktop" 硬拼——OneDrive/自定义重定向会漏):
+ *   - Windows: 注册表 User Shell Folders(含 OneDrive/自定义重定向);值是 REG_EXPAND_SZ,含 %VAR% 需展开。
+ *              展开用 node 的 process.env(编码正确),所以即便用户名是中文,%USERPROFILE% 模板展开后仍准;
+ *              只有用户把桌面手动重定向到硬编码中文路径时,reg 的 OEM 输出可能乱码 → existsSync 兜底回退。
+ *   - macOS:   ~/Desktop 等固定英文路径(Finder 里的本地化名只是显示,真实路径是英文)。
+ *   - Linux:   XDG user-dirs(~/.config/user-dirs.dirs 的 XDG_DESKTOP_DIR 等),回退 ~/Desktop。
+ * 一次性探测 + 缓存(目录在进程生命周期内不变)。任何一项失败都回退到 homedir 拼接,绝不抛。
+ */
+export interface UserDirs {
+    desktop: string;
+    downloads: string;
+    documents: string;
+}
+/** 用户桌面/下载/文档的真实绝对路径(缓存)。失败项回退 homedir 拼接,绝不抛。 */
+export declare function getUserDirs(): UserDirs;
+/** 仅测试用:清缓存,让不同平台/环境的断言各自重探。 */
+export declare function resetUserDirsCache(): void;

package/dist/types/runtime/permission-model.d.ts

@@ -3,7 +3,7 @@ export interface PermissionPromptOption {
     optionId: string;
     name: string;
     kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
-    scope?: "once" | "directory";
+    scope?: "once" | "directory" | "directory_persistent";
 }
 export interface PermissionModeDescriptor {
     id: PermissionMode;

package/dist/types/runtime/ports/permission-contracts.d.ts

@@ -105,8 +105,11 @@ export interface ApprovalResponse {
     approvalId: string;
     decision: "allow" | "deny";
     updatedInput?: Record<string, unknown>;
-    /** Approval scope chosen by the user: just this call, or the whole directory. */
-    scope?: "once" | "directory";
+    /**
+     * Approval scope chosen by the user: just this call, the whole directory for
+     * this session, or the whole directory persisted across restarts.
+     */
+    scope?: "once" | "directory" | "directory_persistent";
 }
 export interface PermissionRuleEnginePort {
     getMode(): PermissionMode;

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/fresh-workspace-evidence.d.ts

@@ -11,9 +11,8 @@ export interface ToolNameLike {
 }
 export interface FreshWorkspaceEvidencePolicy {
     requiresFreshTool: boolean;
-    reason?: "file-read" | "file-mutation" | "memory-mutation" | "media-generation" | "directory-list" | "content-search" | "shell" | "web";
+    reason?: "file-read" | "memory-mutation" | "media-generation" | "directory-list" | "content-search" | "shell" | "web";
     mediaKind?: "image" | "tts" | "music";
-    workflowKind?: "artifact-index";
     allowedToolNames: string[];
 }
 export declare function getFreshWorkspaceEvidencePolicy(messages: readonly PromptMessageLike[] | string): FreshWorkspaceEvidencePolicy;

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 {
+    /** 产品名（运营可配置），缺省 AstraClaw */
+    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/native/claude-session-source.d.ts

@@ -0,0 +1,23 @@
+import type { NativeSessionEntry, NativeSessionRef, NativeSessionSource, TranscriptMessage } from "./native-session-source.js";
+/**
+ * Native session source for Claude Code (claude CLI). Reads directly from
+ * `~/.claude/projects/<claudeProjectDirName(cwd)>/<sessionUuid>.jsonl` — the same on-disk format
+ * Claude Code itself writes, so this is read-only and never touched by qlogicagent.
+ *
+ * `isSidechain: true` events are subagent side-chains, not part of the user-visible conversation,
+ * and are filtered out of both list() (message counting / title / lastActiveAt) and
+ * loadTranscript() (transcript body).
+ */
+export declare class ClaudeSessionSource implements NativeSessionSource {
+    private readonly home;
+    readonly agentId = "claude";
+    readonly kind: "claude";
+    /** `home` is injectable so tests can point at a temp directory instead of the real user home. */
+    constructor(home?: string);
+    list(cwd: string, opts?: {
+        limit?: number;
+    }): Promise<NativeSessionEntry[]>;
+    /** A claude native session is exactly the file `<encoded-cwd>/<sessionUuid>.jsonl` — a single stat. */
+    has(sessionId: string, cwd: string): Promise<boolean>;
+    loadTranscript(ref: NativeSessionRef): Promise<TranscriptMessage[]>;
+}

package/dist/types/runtime/session/native/codex-index.d.ts

@@ -0,0 +1,21 @@
+import type { NativeSessionEntry } from "./native-session-source.js";
+/**
+ * Lists codex-native sessions belonging to `normalizedTargetCwd` (already run through
+ * {@link normalizeCwd} by the caller), sorted by `lastActiveAt` descending.
+ *
+ * Synchronous by design — built entirely on sync fs calls, since it's a Cut 3 building block; a
+ * future CodexSessionSource adapter (mirroring claude-session-source.ts's shape) would wrap this in
+ * the async `NativeSessionSource.list()` contract.
+ *
+ * `messageCount` is always 0: unlike claude's one-line-per-message transcript format, a codex
+ * rollout interleaves many event types per turn, so computing an exact count means fully parsing
+ * every candidate rollout's entire event stream — deliberately out of scope here. Revisit if/when a
+ * caller actually needs an exact count.
+ *
+ * Never throws: a missing/unreadable codexHome, sessions dir, session_index.jsonl, or cache file all
+ * degrade to "as if empty" rather than propagating an error.
+ */
+export declare function listCodexSessionsByCwd(normalizedTargetCwd: string, opts?: {
+    codexHome?: string;
+    cacheDir?: string;
+}): NativeSessionEntry[];

package/dist/types/runtime/session/native/codex-session-source.d.ts

@@ -0,0 +1,31 @@
+import type { NativeSessionEntry, NativeSessionRef, NativeSessionSource, TranscriptMessage } from "./native-session-source.js";
+/**
+ * Native session source for Codex (codex CLI / codex_cli_rs) — Cut 3 Task 3.2.
+ *
+ * `list()` delegates entirely to {@link listCodexSessionsByCwd} (Task 3.1), which already handles
+ * cwd filtering, title/lastActiveAt joining against session_index.jsonl, and mtime-keyed caching;
+ * this adapter only adds the async `NativeSessionSource.list()` contract and cwd normalization on
+ * top of that synchronous building block (mirroring ClaudeSessionSource's shape).
+ *
+ * `loadTranscript()` reads a single rollout file and keeps only `event_msg` lines whose payload is
+ * `user_message` or `agent_message` with `phase: "final_answer"` — see {@link CodexEventMsgLine}'s
+ * doc for why every other line/event/payload type in a rollout is intentionally skipped.
+ */
+export declare class CodexSessionSource implements NativeSessionSource {
+    private readonly opts;
+    readonly agentId = "codex";
+    readonly kind: "codex";
+    /** `opts` is injectable (codexHome/cacheDir) so tests can point at temp directories instead of
+     *  the real user home — mirrors listCodexSessionsByCwd's own opts shape. */
+    constructor(opts?: {
+        codexHome?: string;
+        cacheDir?: string;
+    });
+    list(cwd: string, opts?: {
+        limit?: number;
+    }): Promise<NativeSessionEntry[]>;
+    /** Codex has no id->file mapping without the index (id lives in each rollout's session_meta), so
+     *  membership goes through the mtime-cached listCodexSessionsByCwd (no full re-scan when warm). */
+    has(sessionId: string, cwd: string): Promise<boolean>;
+    loadTranscript(ref: NativeSessionRef): Promise<TranscriptMessage[]>;
+}

package/dist/types/runtime/session/native/cwd-normalize.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Normalize a cwd for CODEX session-cwd equality comparisons (matching a codex rollout's
+ * `session_meta.cwd` against our own workspace cwd). Same rule in spirit as projectId derivation
+ * (see agent-paths.ts `deriveProjectId`: resolve + lowercase) — resolve to an absolute path, then
+ * lowercase and force forward-slash separators so both `E:\Foo\Bar` and `e:/foo/bar` compare equal.
+ * (path.resolve() already normalizes `/` to `\` on win32, so the explicit slash replace below is
+ * belt-and-suspenders rather than load-bearing — verified via `path.resolve("e:/xiaozhiclaw/openclaw")`
+ * === `"e:\\xiaozhiclaw\\openclaw"` on this machine — but kept explicit so the output format doesn't
+ * silently depend on that internal, unstated Node behavior.)
+ */
+export declare function normalizeCwd(cwd: string): string;
+/**
+ * Encode a cwd into the directory name Claude Code uses under `~/.claude/projects/<encoded>`.
+ *
+ * This is Claude Code's OWN encoding (not ours) — we must replicate it byte-for-byte to locate
+ * existing native claude session directories on disk. It has no public spec, so this was reverse
+ * engineered two ways and cross-checked against each other:
+ *
+ *   1. Real directory names from `ls ~/.claude/projects` on this dev machine (see
+ *      cwd-normalize.test.ts for the samples, notably a workspace with a literal space in its name
+ *      — "QA Agent Mention Pool 20260701-1325" — which is what falsified the initially-assumed
+ *      narrower rule).
+ *   2. Decompiling the bundled VS Code extension (anthropic.claude-code-2.1.168,
+ *      extension/extension.js). The relevant minified functions (renamed here for readability;
+ *      originals were Hv/yv/pOe/cOe):
+ *
+ *        const MAX_LEN = 200;
+ *        function hashCode(e) {                               // Java String.hashCode()-style,
+ *          let t = 0;                                          // 32-bit signed, wraps via `|0`
+ *          for (let r = 0; r < e.length; r++) t = (t << 5) - t + e.charCodeAt(r) | 0;
+ *          return t;
+ *        }
+ *        function encodeProjectDirName(e) {
+ *          const t = e.replace(/[^a-zA-Z0-9]/g, "-");
+ *          if (t.length <= MAX_LEN) return t;
+ *          return `${t.slice(0, MAX_LEN)}-${Math.abs(hashCode(e)).toString(36)}`;
+ *        }
+ *
+ * Two things this rule does that a naive "just swap \\/:. for -" guess would get wrong:
+ *   - The replacement set is "everything that isn't [a-zA-Z0-9]", not a fixed 4-character set —
+ *     spaces, underscores, parens, plus signs, and non-ASCII (e.g. Chinese) characters are all
+ *     replaced too. Original casing is preserved (no lowercasing, unlike normalizeCwd above).
+ *   - Encoded names longer than 200 characters are truncated to 200 chars plus a
+ *     "-<base36 32-bit hash>" suffix, where the hash is computed over the ORIGINAL
+ *     (pre-replacement) string, not the truncated one.
+ *
+ * This encoding is lossy/one-way by construction (e.g. `...\\qlogicagent-hub` and
+ * `...\\qlogicagent\\hub` both encode to the same name) — it can only be used to look up a
+ * directory for a known cwd, never to recover a cwd from a directory name. If Claude Code changes
+ * this encoding in a future version, update this function and the fixtures in
+ * cwd-normalize.test.ts together.
+ */
+export declare function claudeProjectDirName(cwd: string): string;

package/dist/types/runtime/session/native/ephemeral-rollout-sweep.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sweep both native stores. Best-effort: never throws (all I/O is guarded); returns how many rollouts were
+ * reclaimed. `home`/`codexHome`/`ttlMs`/`now` are injectable for tests.
+ */
+export declare function sweepEphemeralWorktreeRollouts(opts?: {
+    home?: string;
+    codexHome?: string;
+    ttlMs?: number;
+    now?: number;
+}): Promise<{
+    claudeDeleted: number;
+    codexDeleted: number;
+}>;

package/dist/types/runtime/session/native/native-cwd-agents.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Single source of truth for WHICH third-party ACP backend ids have local, cwd-discoverable
+ * native session history ("native-cwd" adapters registered in register-builtin-sources.ts).
+ *
+ * Consumed by both:
+ *  - acp-detector.ts (assembleBackendDescriptor) — descriptor's capabilities.sessionHistory
+ *  - session-handler.ts (resolveAgentSessionHistory) — session.list routing
+ *
+ * so the two can never drift on which ids are native-adapted (the DRY debt Cut 1 intentionally
+ * left behind — see Cut 3 Task 3.0). To add or remove a native-cwd agent: change this set AND
+ * register/unregister the matching NativeSessionSource adapter in register-builtin-sources.ts.
+ *
+ * Zero imports by design — this file must stay a dependency-free leaf so both acp-detector.ts and
+ * session-handler.ts (which itself imports ACP_BACKENDS from acp-detector.ts) can import it without
+ * risking an import cycle.
+ */
+export declare const NATIVE_CWD_BACKEND_IDS: ReadonlySet<string>;

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

@@ -0,0 +1,89 @@
+/**
+ * Native session source registry.
+ *
+ * A "native" session source lets a third-party ACP agent (codex/claude) expose ITS OWN
+ * CWD-scoped session history — recorded by the agent's own CLI, not by qlogicagent — through
+ * the same session.list / session.get surface as our own sessions.
+ *
+ * Cut 1 shipped only the registry contract with a loose shape; no adapter registered itself, so
+ * {@link getNativeSessionSource} always returned undefined and callers (session-handler's
+ * resolveSessionSource) fell back to an empty list for native-cwd agents. Cut 2 refines the
+ * contract below and adds the claude adapter (see claude-session-source.ts) that calls
+ * {@link registerNativeSessionSource}.
+ */
+/** Opaque locator for a single native session's transcript, round-tripped by the frontend without
+ *  interpretation (session.list returns it, session.loadNativeTranscript consumes it). */
+export interface NativeSessionRef {
+    agentId: string;
+    kind: "codex" | "claude";
+    /** Absolute path to the on-disk transcript file (adapter-specific format). */
+    file: string;
+}
+/** One native session list entry — the `source: "native"` variant of session.list's
+ *  SessionListEntry (see session-types.ts SessionListEntry for the "own" counterpart). */
+export interface NativeSessionEntry {
+    sessionId: string;
+    source: "native";
+    agentId: string;
+    title?: string;
+    lastActiveAt: string;
+    messageCount: number;
+    cwd: string;
+    nativeRef: NativeSessionRef;
+    /** Stamped by handleSessionList from the requested project so the frontend's per-project grouping
+     *  (project-tree filters by projectId) shows native entries under it. The source discovers by cwd
+     *  and cannot know the project, so it leaves this unset. */
+    projectId?: string;
+}
+/**
+ * Minimal transcript-line shape for native session.loadTranscript. This intentionally does NOT
+ * import the frontend's `InboundMessagePayload` (ui-next/src/types/gateway.ts) — that type lives
+ * in a separate package/repo from this engine and carries many fields irrelevant to a bare
+ * transcript line (sessionKey, blocks, attachments, mediaUrl, chatId, ...). Instead this is the
+ * minimal subset every native adapter can populate, documented field-for-field against the
+ * frontend contract so a caller can widen a TranscriptMessage into an InboundMessagePayload by
+ * filling in the rest as optional/absent:
+ *   - messageId -> InboundMessagePayload.messageId (required)
+ *   - content   -> InboundMessagePayload.content (required)
+ *   - timestamp -> InboundMessagePayload.timestamp (required)
+ *   - source    -> InboundMessagePayload.source (required, narrowed here to "user"|"assistant"
+ *                  since that's all a transcript line can be)
+ *   - platform  -> InboundMessagePayload.platform (required there; optional here since every
+ *                  current adapter always sets it to "desktop" — kept optional so future adapters
+ *                  aren't forced to fabricate a value)
+ */
+export interface TranscriptMessage {
+    messageId: string;
+    content: string;
+    timestamp: string;
+    source: "user" | "assistant";
+    platform?: string;
+}
+export interface NativeSessionSource {
+    readonly agentId: string;
+    readonly kind: "codex" | "claude";
+    /** `cwd` is the RAW (un-normalized) project cwd — callers (session-handler's
+     *  resolveSessionSource, via handleSessionList) pass the REQUESTED project's workspaceDir
+     *  (params.projectId's, when present) straight through, falling back to getActiveProjectRoot()
+     *  only when no projectId was given. Each adapter is responsible for whatever
+     *  normalization/encoding its own on-disk storage requires (e.g. claude's
+     *  claudeProjectDirName preserves original casing). */
+    list(cwd: string, opts?: {
+        limit?: number;
+    }): Promise<NativeSessionEntry[]>;
+    /** Cheap existence check: is `sessionId` an existing native session under `cwd` for this agent?
+     *  Used on a COLD spawn to decide whether to resume it (ACP session/load) instead of creating a
+     *  fresh session — so a native conversation regains its authoritative history after pool eviction/
+     *  restart, not only on the one-shot "继续". Optional so test fakes need not implement it. */
+    has?(sessionId: string, cwd: string): Promise<boolean>;
+    loadTranscript(ref: NativeSessionRef): Promise<TranscriptMessage[]>;
+}
+/** Register a native session source for an agentId. Last registration for a given id wins. */
+export declare function registerNativeSessionSource(source: NativeSessionSource): void;
+/** Look up a registered native session source by agentId. Undefined when none is registered for
+ *  that id (no adapter registered itself yet, or the agentId has no native adapter at all). */
+export declare function getNativeSessionSource(agentId?: string): NativeSessionSource | undefined;
+/** Remove a registered native session source by agentId. Symmetric with {@link registerNativeSessionSource};
+ *  exists primarily so tests can deregister a fake adapter afterward without leaking it into other
+ *  test cases that share this module-level registry. No-op if nothing is registered for that id. */
+export declare function unregisterNativeSessionSource(agentId: string): void;

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

@@ -0,0 +1 @@
+export declare function cleanNativeTitle(message: string, maxLen?: number): string | undefined;

package/dist/types/runtime/session/native/register-builtin-sources.d.ts

@@ -0,0 +1 @@
+export declare function registerBuiltinNativeSources(): void;

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 {};