wave-agent-sdk 1.1.5 → 1.3.0

package/dist/services/officialMarketplaceMirror.js

@@ -0,0 +1,290 @@
+/**
+ * Builtin official marketplace zip-snapshot mirror fetch.
+ *
+ * The official marketplace (wave-plugins-official, BUILTIN in MarketplaceService)
+ * is hosted on GitHub, which is poorly reachable from CN networks. Instead of a
+ * dumb-HTTP git endpoint we mirror the "content-addressed zip + latest pointer +
+ * local sentinel" model Claude Code uses for its official marketplace
+ * (officialMarketplaceGcs.ts, inc-5046):
+ *
+ *   1. GET `{base}/latest` (10s timeout) → content-addressed sha
+ *   2. Compare against the local sentinel `.wave-market-sha` at the market root
+ *      — equal ⇒ no-op (idempotent, one ~40B request per run)
+ *   3. GET `{base}/{sha}.zip` (60s timeout) → extract into a `.staging` dir
+ *      (path-traversal/absolute-path rejection, size limits, exec-bit restore
+ *      from zip external attrs)
+ *   4. Atomic swap: rm old market dir + rename staging → market dir, write the
+ *      sentinel back
+ *
+ * Any failure returns null; the caller decides whether to fall through to the
+ * existing git path (guarded by a kill switch, mirroring Claude's
+ * tengu_plugin_official_mkt_git_fallback flag).
+ */
+import { chmod, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { unzipSync } from "fflate";
+import { logWarn } from "../utils/globalLogger.js";
+/** Sentinel file name stored at the market root holding the last fetched sha. */
+export const OFFICIAL_MARKET_SENTINEL_FILE = ".wave-market-sha";
+/** Suffix of the staging dir used for atomic swap into the market root. */
+const STAGING_SUFFIX = ".staging";
+/**
+ * Default mirror base URL (prod contract) — files hang directly off this base:
+ * `{base}/latest` (pure-text sha) and `{base}/{sha}.zip` (whole-tree snapshot).
+ * Trailing slash is normalized away when composing URLs.
+ *
+ * - PROD: `https://codechat.codewave.163.com/wave-plugins-official/`
+ * - TEST（验证用）: `https://codechat.codewave-test.163yun.com/wave-plugins-official/`
+ *
+ * Override with env var `WAVE_OFFICIAL_MARKET_MIRROR_BASE_URL` (highest
+ * precedence). 两套环境的镜像通道均已上线且有内容（2026-09-23 实测：prod 与 test 的
+ * `/latest` 均返回 sha、`{sha}.zip` 均可下载）。镜像请求若失败（网络/超时/404/内容异常），
+ * 仍按既有设计回退 git 兜底（ALLOW_OFFICIAL_MARKET_GIT_FALLBACK），语义不变。
+ */
+const DEFAULT_OFFICIAL_MARKET_MIRROR_BASE_URL = "https://codechat.codewave.163.com/wave-plugins-official/";
+/** Env var override for the mirror base URL (highest precedence). */
+export const OFFICIAL_MARKET_MIRROR_BASE_URL_ENV = "WAVE_OFFICIAL_MARKET_MIRROR_BASE_URL";
+/**
+ * Kill switch for the git fallback after a mirror failure (default: allowed).
+ * Mirrors Claude Code's `tengu_plugin_official_mkt_git_fallback` flag. When
+ * false and the mirror fails, the builtin marketplace update is skipped
+ * (retried on next run) instead of hitting GitHub.
+ */
+export const ALLOW_OFFICIAL_MARKET_GIT_FALLBACK = true;
+const LATEST_TIMEOUT_MS = 10000;
+const ZIP_TIMEOUT_MS = 60000;
+// Sanity limits against corrupt/malicious archives (zip bombs). The publisher
+// is first-party, so these are corruption guards rather than a trust boundary;
+// values follow the Claude Code reference (utils/dxt/zip.ts).
+const ZIP_LIMITS = {
+    MAX_SINGLE_FILE_SIZE: 512 * 1024 * 1024, // per-file uncompressed
+    MAX_TOTAL_SIZE: 1024 * 1024 * 1024, // total uncompressed
+    MAX_FILE_COUNT: 100000,
+    MAX_COMPRESSION_RATIO: 50, // uncompressed : compressed
+};
+/**
+ * Resolves the mirror base URL: env var wins, otherwise the built-in constant.
+ * Returns null when neither is configured (mirror channel disabled).
+ */
+export function resolveOfficialMarketplaceMirrorBaseUrl() {
+    const envUrl = process.env[OFFICIAL_MARKET_MIRROR_BASE_URL_ENV];
+    const candidate = (envUrl && envUrl.trim()) || DEFAULT_OFFICIAL_MARKET_MIRROR_BASE_URL;
+    if (!candidate)
+        return null;
+    return candidate.replace(/\/+$/, ""); // normalize trailing slashes
+}
+/**
+ * Rejects zip entry paths that would escape the extraction root: absolute
+ * paths (POSIX or Windows drive/UNC), `..` segments, and null bytes. Paths
+ * use either `/` or `\` as separator. Returns the normalized relative path on
+ * success or null for entries that must be skipped (empty/directory-only is
+ * handled by the caller via the trailing `/`).
+ */
+export function sanitizeZipEntryPath(entryPath) {
+    if (!entryPath || entryPath.includes("\0"))
+        return null;
+    if (entryPath.startsWith("/") || entryPath.startsWith("\\"))
+        return null;
+    const segments = entryPath.split(/[\\/]/);
+    // A drive-letter prefix (Windows "C:/…") must not slip through as relative.
+    if (segments[0] && /^[A-Za-z]:$/.test(segments[0]))
+        return null;
+    for (const seg of segments) {
+        if (seg === "..")
+            return null;
+    }
+    return entryPath;
+}
+/**
+ * Fetches the official marketplace from the zip-snapshot mirror and extracts
+ * it to installLocation. Idempotent — compares the local `.wave-market-sha`
+ * sentinel before downloading.
+ *
+ * @param installLocation where to extract (must be inside marketplacesCacheDir)
+ * @param marketplacesCacheDir the marketplace cache root (defense-in-depth:
+ *   this function `rm`s installLocation during the atomic swap)
+ * @param baseUrl optional explicit base URL (tests); defaults to env/constant
+ * @returns the fetched sha on success (including no-op), null on any failure
+ *   (unconfigured mirror, network, 404, corrupt zip, unsafe entries). Caller
+ *   decides whether to fall through to git.
+ */
+export async function fetchOfficialMarketplaceFromMirror(installLocation, marketplacesCacheDir, baseUrl) {
+    // Defense in depth: this function does `rm(installLocation, {recursive})`
+    // during the atomic swap. A corrupted known_marketplaces.json could point
+    // at the user's project. Refuse any path outside the marketplace cache dir.
+    // Same guard as Claude's officialMarketplaceGcs.ts:57-65.
+    const cacheDir = resolve(marketplacesCacheDir);
+    const resolvedLoc = resolve(installLocation);
+    if (resolvedLoc !== cacheDir && !resolvedLoc.startsWith(cacheDir + sep)) {
+        logWarn(`Official marketplace mirror: refusing install location outside marketplaces cache dir: ${installLocation}`);
+        return null;
+    }
+    const effectiveBase = baseUrl ?? resolveOfficialMarketplaceMirrorBaseUrl();
+    if (!effectiveBase)
+        return null; // mirror not configured
+    try {
+        // 1. Latest pointer — tiny request, hit on every startup.
+        const latestText = await httpGetText(`${effectiveBase}/latest`, LATEST_TIMEOUT_MS);
+        const sha = latestText.trim();
+        if (!sha) {
+            // Empty /latest body — mirror misconfigured. Bail (null), don't lock
+            // into a permanently-broken empty-sentinel state.
+            throw new Error("Official marketplace mirror: latest pointer returned empty body");
+        }
+        // sha is interpolated into a URL — keep it a sane opaque token.
+        if (!/^[^\s/\\]+$/.test(sha)) {
+            throw new Error(`Official marketplace mirror: invalid sha from latest pointer`);
+        }
+        // 2. Sentinel check.
+        const currentSha = await readFile(join(installLocation, OFFICIAL_MARKET_SENTINEL_FILE), "utf8")
+            .then((s) => s.trim())
+            .catch(() => null); // ENOENT — first fetch, proceed to download
+        if (currentSha === sha)
+            return sha;
+        // 3. Download zip and extract to a staging dir, then atomic-swap into
+        //    place. A crash mid-extract leaves a .staging dir (rm'd on the next
+        //    run) rather than a half-written installLocation.
+        const zipBuf = await httpGetBuffer(`${effectiveBase}/${sha}.zip`, ZIP_TIMEOUT_MS);
+        const zipState = {
+            fileCount: 0,
+            totalUncompressed: 0,
+            compressedSize: zipBuf.length,
+        };
+        const files = unzipSync(new Uint8Array(zipBuf), {
+            filter: (file) => {
+                validateZipEntry(file.name, file.originalSize, zipState);
+                return true;
+            },
+        });
+        // fflate doesn't surface external_attr, so parse the central directory
+        // ourselves to recover exec bits. Without this, hooks/scripts extract as
+        // 0644 and fail to execute — git clone preserves +x natively, so the zip
+        // path must too.
+        const modes = parseZipModes(zipBuf);
+        const staging = `${installLocation}${STAGING_SUFFIX}`;
+        await rm(staging, { recursive: true, force: true });
+        await mkdir(staging, { recursive: true });
+        for (const [entryName, data] of Object.entries(files)) {
+            if (!entryName || entryName.endsWith("/"))
+                continue; // dir entries
+            const rel = sanitizeZipEntryPath(entryName);
+            if (!rel)
+                continue; // validated in filter; skip defensively
+            const dest = join(staging, rel);
+            await mkdir(dirname(dest), { recursive: true });
+            await writeFile(dest, data);
+            const mode = modes[entryName];
+            if (mode && mode & 0o111) {
+                // Only chmod when an exec bit is set — skip plain files to save
+                // syscalls. Swallow EPERM/ENOTSUP (read-only mounts) — losing +x is
+                // better than aborting mid-extraction.
+                await chmod(dest, mode & 0o777).catch(() => { });
+            }
+        }
+        await writeFile(join(staging, OFFICIAL_MARKET_SENTINEL_FILE), sha);
+        // 4. Atomic swap: rm old, rename staging. Brief window where
+        //    installLocation doesn't exist — acceptable for a background refresh
+        //    (next run re-downloads if it crashes here).
+        await rm(installLocation, { recursive: true, force: true });
+        await rename(staging, installLocation);
+        return sha;
+    }
+    catch (error) {
+        logWarn(`Official marketplace mirror fetch failed (falling back per caller policy): ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/**
+ * Validates one zip entry (called from the fflate filter). Throws to abort the
+ * whole extraction when an entry is unsafe or the archive exceeds limits.
+ */
+export function validateZipEntry(name, originalSize, state) {
+    state.fileCount++;
+    if (state.fileCount > ZIP_LIMITS.MAX_FILE_COUNT) {
+        throw new Error(`Official marketplace zip contains too many files (${state.fileCount}, max ${ZIP_LIMITS.MAX_FILE_COUNT})`);
+    }
+    const clean = sanitizeZipEntryPath(name);
+    if (!clean) {
+        // Reject unsafe entries (path traversal, absolute paths, null bytes).
+        // Directory entries are validated too — a `../` dir entry aborts.
+        throw new Error(`Official marketplace zip contains unsafe path: "${name}"`);
+    }
+    if (originalSize > ZIP_LIMITS.MAX_SINGLE_FILE_SIZE) {
+        throw new Error(`Official marketplace zip entry "${name}" too large (${originalSize} bytes, max ${ZIP_LIMITS.MAX_SINGLE_FILE_SIZE})`);
+    }
+    state.totalUncompressed += originalSize;
+    if (state.totalUncompressed > ZIP_LIMITS.MAX_TOTAL_SIZE) {
+        throw new Error(`Official marketplace zip total size exceeds ${ZIP_LIMITS.MAX_TOTAL_SIZE} bytes`);
+    }
+    if (state.compressedSize > 0 &&
+        state.totalUncompressed / state.compressedSize >
+            ZIP_LIMITS.MAX_COMPRESSION_RATIO) {
+        throw new Error(`Official marketplace zip suspicious compression ratio (>${ZIP_LIMITS.MAX_COMPRESSION_RATIO}:1) — possible zip bomb`);
+    }
+}
+async function httpGetText(url, timeoutMs) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status} fetching ${url}`);
+    }
+    return response.text();
+}
+async function httpGetBuffer(url, timeoutMs) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status} fetching ${url}`);
+    }
+    return Buffer.from(await response.arrayBuffer());
+}
+/**
+ * Parse Unix file modes from a zip's central directory.
+ *
+ * fflate's `unzipSync` returns only `Record<string, Uint8Array>` — it does not
+ * surface the external file attributes stored in the central directory, so
+ * executable bits would be lost (everything extracts as 0644). Returns
+ * `name → mode` for entries created on a Unix host (`versionMadeBy` high byte
+ * === 3); other entries are omitted and extract with default mode.
+ *
+ * Format per PKZIP APPNOTE.TXT §4.3.12 (central directory) and §4.3.16 (EOCD).
+ * ZIP64 is not handled — returns `{}` on archives >4GB or >65535 entries,
+ * which is fine for marketplace zips.
+ */
+export function parseZipModes(data) {
+    const buf = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    const modes = {};
+    // 1. Find the End of Central Directory record (sig 0x06054b50). Scan
+    //    backwards from the trailing 22 + max-comment bytes.
+    const minEocd = Math.max(0, buf.length - 22 - 0xffff);
+    let eocd = -1;
+    for (let i = buf.length - 22; i >= minEocd; i--) {
+        if (buf.readUInt32LE(i) === 0x06054b50) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd < 0)
+        return modes; // malformed — the unzip error surfaces separately
+    const entryCount = buf.readUInt16LE(eocd + 10);
+    let off = buf.readUInt32LE(eocd + 16);
+    // 2. Walk central directory entries (sig 0x02014b50). Each entry has a
+    //    46-byte fixed header followed by variable-length name/extra/comment.
+    for (let i = 0; i < entryCount; i++) {
+        if (off + 46 > buf.length || buf.readUInt32LE(off) !== 0x02014b50)
+            break;
+        const versionMadeBy = buf.readUInt16LE(off + 4);
+        const nameLen = buf.readUInt16LE(off + 28);
+        const extraLen = buf.readUInt16LE(off + 30);
+        const commentLen = buf.readUInt16LE(off + 32);
+        const externalAttr = buf.readUInt32LE(off + 38);
+        const name = buf.toString("utf8", off + 46, off + 46 + nameLen);
+        // versionMadeBy high byte = host OS. 3 = Unix. For Unix zips the high 16
+        // bits of externalAttr hold st_mode (file type + permission bits).
+        if (versionMadeBy >> 8 === 3) {
+            const mode = (externalAttr >>> 16) & 0xffff;
+            if (mode)
+                modes[name] = mode;
+        }
+        off += 46 + nameLen + extraLen + commentLen;
+    }
+    return modes;
+}

package/dist/services/pluginLoader.d.ts

@@ -1,4 +1,4 @@
-import { PluginManifest, CustomSlashCommand, Skill, LspConfig, McpConfig, PartialHookConfiguration } from "../types/index.js";
+import { PluginManifest, CustomSlashCommand, Skill, LspConfig, McpConfig, McpServerConfig, PartialHookConfiguration } from "../types/index.js";
 import { type SubagentConfiguration } from "../utils/subagentParser.js";
 export declare class PluginLoader {
     /**
@@ -21,9 +21,17 @@ export declare class PluginLoader {
      */
     static loadLspConfig(pluginPath: string): Promise<LspConfig | undefined>;
     /**
-     * Load MCP configuration from a plugin
-     */
-    static loadMcpConfig(pluginPath: string): Promise<McpConfig | undefined>;
+     * Load MCP configuration from a plugin.
+     *
+     * Accepts both declaration shapes found in the wild (spec plugin A-023): the
+     * wrapped `{"mcpServers": {…}}` and the flat `{"<serverName>": {…}}`, matching
+     * Claude Code's `parsed.mcpServers || parsed`. A plugin manifest that declares
+     * `mcpServers` inline is equivalent to a sibling `.mcp.json`; when both exist
+     * they are merged by server name, the file winning.
+     *
+     * @param manifestMcpServers Inline declarations from the plugin manifest
+     */
+    static loadMcpConfig(pluginPath: string, manifestMcpServers?: Record<string, McpServerConfig>): Promise<McpConfig | undefined>;
     /**
      * Load hooks configuration from a plugin
      */

package/dist/services/pluginLoader.js

@@ -128,18 +128,33 @@ export class PluginLoader {
         }
     }
     /**
-     * Load MCP configuration from a plugin
+     * Load MCP configuration from a plugin.
+     *
+     * Accepts both declaration shapes found in the wild (spec plugin A-023): the
+     * wrapped `{"mcpServers": {…}}` and the flat `{"<serverName>": {…}}`, matching
+     * Claude Code's `parsed.mcpServers || parsed`. A plugin manifest that declares
+     * `mcpServers` inline is equivalent to a sibling `.mcp.json`; when both exist
+     * they are merged by server name, the file winning.
+     *
+     * @param manifestMcpServers Inline declarations from the plugin manifest
      */
-    static async loadMcpConfig(pluginPath) {
+    static async loadMcpConfig(pluginPath, manifestMcpServers) {
+        const servers = {
+            ...(manifestMcpServers ?? {}),
+        };
         const mcpPath = path.join(pluginPath, ".mcp.json");
         try {
             const content = await fs.readFile(mcpPath, "utf-8");
+            const parsed = JSON.parse(content);
             // Return raw config — let McpManager resolve templates and capture originalUrl
-            return JSON.parse(content);
+            Object.assign(servers, extractMcpServers(parsed));
         }
         catch {
-            return undefined;
+            // no .mcp.json — inline declarations (if any) stand alone
         }
+        if (Object.keys(servers).length === 0)
+            return undefined;
+        return { mcpServers: servers };
     }
     /**
      * Load hooks configuration from a plugin
@@ -197,11 +212,27 @@ export class PluginLoader {
         if (!manifest.description) {
             throw new Error("Plugin manifest missing 'description'");
         }
-        if (!manifest.version) {
-            throw new Error("Plugin manifest missing 'version'");
-        }
+        // `version` is optional: the Claude Code ecosystem omits it freely and the
+        // install path already defaults it (spec plugin A-022).
         if (!/^[a-z0-9-]+$/.test(manifest.name)) {
             throw new Error(`Invalid plugin name: ${manifest.name}. Only lowercase letters, numbers, and hyphens are allowed.`);
         }
     }
 }
+/**
+ * Normalizes an MCP declaration to a server map, accepting both the wrapped and
+ * the flat shape (spec plugin A-023). Anything that is not an object of server
+ * configs yields an empty map rather than throwing, so one malformed declaration
+ * cannot fail the whole plugin.
+ */
+function extractMcpServers(parsed) {
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {};
+    }
+    const record = parsed;
+    const wrapped = record.mcpServers;
+    const servers = wrapped && typeof wrapped === "object" && !Array.isArray(wrapped)
+        ? wrapped
+        : record;
+    return servers;
+}

package/dist/services/remoteSettingsService.js

@@ -268,8 +268,8 @@ export function mergeRemoteSettings(localMerged, remote) {
             deny: lp.deny || rp.deny
                 ? dedupe([...(lp.deny ?? []), ...(rp.deny ?? [])])
                 : undefined,
-            // permissionMode: remote wins (scalar)
-            permissionMode: rp.permissionMode ?? lp.permissionMode,
+            // defaultMode: remote wins (scalar)
+            defaultMode: rp.defaultMode ?? lp.defaultMode,
             // additionalDirectories: concatenate + dedupe
             additionalDirectories: lp.additionalDirectories || rp.additionalDirectories
                 ? dedupe([
@@ -283,8 +283,8 @@ export function mergeRemoteSettings(localMerged, remote) {
             delete result.permissions.allow;
         if (!result.permissions.deny)
             delete result.permissions.deny;
-        if (!result.permissions.permissionMode)
-            delete result.permissions.permissionMode;
+        if (!result.permissions.defaultMode)
+            delete result.permissions.defaultMode;
         if (!result.permissions.additionalDirectories)
             delete result.permissions.additionalDirectories;
     }
@@ -303,12 +303,26 @@ export function mergeRemoteSettings(localMerged, remote) {
         result.worktree = remote.worktree;
     if (remote.models !== undefined)
         result.models = remote.models;
+    // Plugin / marketplace maps merge per key (remote wins per key), like `env`
+    // above: the managed layer's keys override same-named local ones while every
+    // key the admin did not mention stays as the user configured it. A wholesale
+    // replace would silently drop all of a user's own plugins the moment an admin
+    // pushes a single managed one (spec enterprise server-managed-config
+    // 「托管配置下发插件市场与启用列表」场景 5, matching Claude Code's policy layer).
     if (remote.marketplaces !== undefined)
-        result.marketplaces = remote.marketplaces;
+        result.marketplaces = {
+            ...localMerged.marketplaces,
+            ...remote.marketplaces,
+        };
     if (remote.enabledPlugins !== undefined)
-        result.enabledPlugins = remote.enabledPlugins;
+        result.enabledPlugins = {
+            ...localMerged.enabledPlugins,
+            ...remote.enabledPlugins,
+        };
     if (remote.enableArtifact !== undefined)
         result.enableArtifact = remote.enableArtifact;
+    if (remote.enableExec !== undefined)
+        result.enableExec = remote.enableExec;
     return result;
 }
 /**

package/dist/services/session.d.ts

@@ -22,6 +22,13 @@ export interface SessionData {
         workdir: string;
         lastActiveAt: string;
         latestTotalTokens: number;
+        /**
+         * User-set title recovered from the whole-file scan (see
+         * `readMessagesAndCustomTitle`). Held in memory by the host so a later
+         * `reAppendSessionMetadata` can write it back at EOF even after later
+         * messages pushed it out of the tail window.
+         */
+        customTitle?: string;
     };
 }
 export interface SessionMetadata {
@@ -33,6 +40,11 @@ export interface SessionMetadata {
     lastActiveAt: Date;
     latestTotalTokens: number;
     firstMessage?: string;
+    /**
+     * User-set conversation title (from a `custom-title` entry in the session
+     * file). Takes precedence over `firstMessage` when rendering a label.
+     */
+    customTitle?: string;
     /** Git branch at session creation time (from the metadata header). */
     branch?: string;
 }
@@ -75,6 +87,21 @@ export declare function getSessionFilePath(sessionId: string, workdir: string, s
  * @param sessionType - Type of session ("main" or "subagent", defaults to "main")
  */
 export declare function createSession(sessionId: string, workdir: string, sessionType?: "main" | "subagent"): Promise<void>;
+/**
+ * Rewrite a session file down to its first `keepMessageCount` messages.
+ *
+ * The only caller is `/rewind`. Unlike `appendMessages` this removes history
+ * from the file, but it keeps every file-level reserved entry (metadata header,
+ * `custom-title`) byte for byte — dropping them would silently turn the session
+ * into the "legacy file without a header" shape, losing its creation time,
+ * git branch and user-set title.
+ *
+ * @param sessionId - UUID session identifier
+ * @param keepMessageCount - Number of leading messages to keep
+ * @param workdir - Working directory for the session
+ * @param sessionType - Type of session ("main" or "subagent", defaults to "main")
+ */
+export declare function truncateSession(sessionId: string, keepMessageCount: number, workdir: string, sessionType?: "main" | "subagent"): Promise<void>;
 /**
  * Append messages to session using JSONL format (new approach)
  *
@@ -84,6 +111,53 @@ export declare function createSession(sessionId: string, workdir: string, sessio
  * @param sessionType - Type of session ("main" or "subagent", defaults to "main")
  */
 export declare function appendMessages(sessionId: string, newMessages: Message[], workdir: string, sessionType?: "main" | "subagent"): Promise<void>;
+/**
+ * Set (or replace) a session's user-set title.
+ *
+ * The title is persisted as a `custom-title` entry appended to the session's
+ * own JSONL file — never as a rewrite of the metadata header, and never in a
+ * sidecar index — so every host that reads session files sees it without any
+ * extra sync channel.
+ *
+ * A session whose transcript has not been materialized yet (only meta messages
+ * so far) is created here: renaming is an explicit user action, so it is not
+ * subject to the "meta-only sessions never hit disk" rule.
+ *
+ * An empty/blank title is a no-op — it is not a signal to clear the title.
+ *
+ * @param sessionId - UUID session identifier
+ * @param workdir - Working directory the session belongs to
+ * @param title - New title
+ * @returns The trimmed title that was written, or undefined for a blank no-op
+ */
+export declare function setSessionCustomTitle(sessionId: string, workdir: string, title: string): Promise<string | undefined>;
+/**
+ * Re-append the session's reserved metadata entries at EOF.
+ *
+ * A listing reads only the tail window (64 KB) of each session file, so a
+ * `custom-title` entry that later messages pushed past that window becomes
+ * invisible — the session would flip back to showing its first message. This
+ * runs at the session's sparse flush points (spec `session-management.md`
+ * 验收场景 5): graceful exit, compaction, taking over a resumed session,
+ * switching away from one, and after `/rewind` rewrites the file. Claude Code
+ * solves the same problem the same way (`reAppendSessionMetadata`,
+ * `sessionStorage.ts:458/983/1533`, `compact.ts:711/1057`).
+ *
+ * The entry is refreshed from the tail first: another process (the CLI session
+ * picker, a second host) may have renamed the session while we held it, in
+ * which case its value — not our stale in-memory one — is the truth. When the
+ * tail holds nothing (already evicted, or never written by anyone else), the
+ * caller's in-memory value stands.
+ *
+ * A missing transcript file is a no-op: re-appending must never materialize a
+ * session that does not exist.
+ *
+ * @param sessionId - UUID session identifier
+ * @param workdir - Working directory the session belongs to
+ * @param customTitle - Title held in memory by the caller (may be undefined)
+ * @param sessionType - Type of session ("main" or "subagent", defaults to "main")
+ */
+export declare function reAppendSessionMetadata(sessionId: string, workdir: string, customTitle: string | undefined, sessionType?: "main" | "subagent"): Promise<void>;
 /**
  * Load session data from JSONL file (new approach)
  *