qlogicagent 2.13.4 → 2.13.5

package/dist/runtime/session/session-locator.js

@@ -0,0 +1,91 @@
+/**
+ * SessionLocator — resolves session storage paths from projectId.
+ *
+ * Every session operation uses this locator to determine the correct
+ * filesystem path based on the session's owning projectId.
+ * When projectId is missing, falls back to scanning all projects.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as projectStore from "../infra/project-store.js";
+import { getDefaultPathService } from "../infra/default-path-service.js";
+export class SessionLocator {
+    /** Get sessions root directory for a given projectId. */
+    getSessionsRoot(projectId) {
+        const project = projectStore.getProjectById(projectId);
+        if (!project)
+            throw new Error(`Project not found: ${projectId}`);
+        return getDefaultPathService().getProjectSessionsRoot(project.workspaceDir);
+    }
+    /** Get the workspace dir for a project. */
+    getProjectWorkspaceDir(projectId) {
+        const project = projectStore.getProjectById(projectId);
+        if (!project)
+            throw new Error(`Project not found: ${projectId}`);
+        return project.workspaceDir;
+    }
+    /** Get the session directory path for a given projectId + sessionId. */
+    getSessionDir(projectId, sessionId) {
+        return path.join(this.getSessionsRoot(projectId), sessionId);
+    }
+    /**
+     * Resolve the workspaceDir for a session given its projectId.
+     * If projectId is not provided, scans all projects for the session directory.
+     */
+    resolveWorkspaceDir(sessionId, projectId) {
+        if (projectId) {
+            const project = projectStore.getProjectById(projectId);
+            if (project)
+                return project.workspaceDir;
+            // projectId is unknown to the current owner's store. This happens when a
+            // workspaceDir is shared across owners — the default project exists under
+            // multiple owner profiles with different ids — and a session's metadata still
+            // carries the projectId of whichever owner created it. handleSessionList
+            // tolerates the same mismatch by scanning workspaceDirs, so resolution (and
+            // thus deletion/resume/get) must too: fall through to the scan below instead
+            // of throwing "Project not found".
+        }
+        // Fallback: scan all projects for a directory matching this sessionId
+        const projects = projectStore.listProjects();
+        for (const project of projects) {
+            const sessionsRoot = getDefaultPathService().getProjectSessionsRoot(project.workspaceDir);
+            const sessionDir = path.join(sessionsRoot, sessionId);
+            try {
+                if (fs.existsSync(sessionDir)) {
+                    return project.workspaceDir;
+                }
+            }
+            catch { /* skip inaccessible dirs */ }
+        }
+        // Final fallback: use active project
+        return this.getActiveProjectWorkspaceDir();
+    }
+    /** Get the active project's workspace dir (for new session creation when no projectId specified). */
+    getActiveProjectWorkspaceDir() {
+        const active = projectStore.getActiveProject();
+        if (active)
+            return active.workspaceDir;
+        // Fallback: first active project
+        const projects = projectStore.listProjects();
+        if (projects.length > 0)
+            return projects[0].workspaceDir;
+        throw new Error("No active project available");
+    }
+    /** Get the active project's ID. */
+    getActiveProjectId() {
+        const active = projectStore.getActiveProject();
+        if (active)
+            return active.id;
+        const projects = projectStore.listProjects();
+        if (projects.length > 0)
+            return projects[0].id;
+        throw new Error("No active project available");
+    }
+    /** Get the default project's ID for external personal channel sessions. */
+    getDefaultProjectId() {
+        const defaultProject = projectStore.getDefaultProject();
+        if (defaultProject)
+            return defaultProject.id;
+        throw new Error("No default project available");
+    }
+}

package/dist/runtime/session/session-locator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/session/session-locator.test.js

@@ -0,0 +1,59 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { SessionLocator } from "./session-locator.js";
+// Regression for the "delete archived session" 500: the default project's
+// workspaceDir is shared across owner profiles (each owner has its own default
+// project id pointing at ~/.qlogicagent/workspaces/default). A session's metadata
+// keeps the projectId of whichever owner created it, so when a different owner is
+// active (e.g. after logging into llmrouter, QLOGIC_LLMROUTER_USER_ID flips the
+// owner) that projectId is unknown to the current store. handleSessionList already
+// tolerates this by scanning workspaceDirs; resolveWorkspaceDir must not throw.
+describe("SessionLocator.resolveWorkspaceDir — cross-owner shared workspaceDir", () => {
+    let home;
+    let workspaceDir;
+    beforeEach(() => {
+        home = mkdtempSync(join(tmpdir(), "qa-locator-home-"));
+        workspaceDir = mkdtempSync(join(tmpdir(), "qa-locator-ws-"));
+        vi.stubEnv("QLOGICAGENT_HOME", home);
+        vi.stubEnv("QLOGIC_IMPLICIT_OWNER_ID", "oc_test");
+        // Clear the higher-priority owner overrides so the active owner is deterministic.
+        vi.stubEnv("QLOGIC_LLMROUTER_USER_ID", "");
+        vi.stubEnv("QLOGIC_DEVICE_ID", "");
+        // The current owner (oc_test) owns a default project bound to workspaceDir,
+        // but with a DIFFERENT id than the one a session's metadata might carry.
+        mkdirSync(join(home, "profiles", "oc_test"), { recursive: true });
+        writeFileSync(join(home, "profiles", "oc_test", "projects.json"), JSON.stringify({
+            activeProjectId: "proj-current-owner",
+            projects: [
+                {
+                    id: "proj-current-owner",
+                    name: "默认项目",
+                    workspaceDir,
+                    type: "default",
+                    status: "active",
+                    createdAt: "2026-06-01T00:00:00.000Z",
+                    updatedAt: "2026-06-01T00:00:00.000Z",
+                },
+            ],
+        }));
+        // A session physically lives under the shared workspaceDir.
+        mkdirSync(join(workspaceDir, ".qlogicagent", "sessions", "sess-shared"), { recursive: true });
+    });
+    afterEach(() => {
+        vi.unstubAllEnvs();
+    });
+    it("resolves a session whose projectId belongs to another owner instead of throwing", () => {
+        const locator = new SessionLocator();
+        // "proj-other-owner" is unknown to oc_test's store — this previously threw
+        // "Project not found: proj-other-owner", surfacing as a 500 on session.delete.
+        const resolved = locator.resolveWorkspaceDir("sess-shared", "proj-other-owner");
+        expect(resolved).toBe(workspaceDir);
+    });
+    it("still fast-paths a projectId the current owner does know", () => {
+        const locator = new SessionLocator();
+        const resolved = locator.resolveWorkspaceDir("sess-shared", "proj-current-owner");
+        expect(resolved).toBe(workspaceDir);
+    });
+});

package/dist/runtime/session/session-metadata-store.d.ts

@@ -0,0 +1,8 @@
+import type { SessionMetadata, SessionMetadataPatch, SessionStateSaveMetadata, SessionUsageSnapshot } from "./session-types.js";
+export declare function getSessionMetadata(sessionId: string, projectRoot: string): SessionMetadata | null;
+export declare function readSessionMetadata(sessionId: string, projectRoot: string, defaults?: {
+    messageCount?: number;
+}): Promise<SessionMetadata>;
+export declare function saveSessionState(sessionId: string, usageSnapshot: SessionUsageSnapshot, metadata: SessionStateSaveMetadata, projectRoot: string): Promise<void>;
+export declare function updateSessionMetadata(sessionId: string, patch: SessionMetadataPatch, projectRoot: string): Promise<SessionMetadata | null>;
+export declare function persistTaskSummary(sessionId: string, projectRoot: string, summary: string, generatedAtTurn: number): Promise<void>;

package/dist/runtime/session/session-metadata-store.js

@@ -0,0 +1,167 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { findExistingSessionDir, getMetadataPath, getSessionDir, LEGACY_STATE_FILE, METADATA_FILE, } from "./session-paths.js";
+import { metadataNeedsMigration, normalizeSessionMetadata } from "./session-schema.js";
+import { withSessionWriteLimit } from "./session-write-queue.js";
+function toEpochMillis(value) {
+    if (!value)
+        return Date.now();
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : Date.now();
+}
+async function writeJsonAtomic(filePath, value) {
+    const tmpFile = filePath + ".tmp";
+    await fs.promises.writeFile(tmpFile, JSON.stringify(value, null, 2), "utf8");
+    await fs.promises.rename(tmpFile, filePath);
+}
+function writeJsonAtomicSync(filePath, value) {
+    const tmpFile = filePath + ".tmp";
+    fs.writeFileSync(tmpFile, JSON.stringify(value, null, 2), "utf8");
+    fs.renameSync(tmpFile, filePath);
+}
+async function writeLegacyStateProjection(dir, metadata, usageSnapshot) {
+    const state = {
+        metadata: {
+            sessionId: metadata.sessionId,
+            createdAt: toEpochMillis(metadata.createdAt),
+            lastActiveAt: toEpochMillis(metadata.lastActiveAt),
+            model: metadata.model,
+            cwd: metadata.cwd,
+            turnCount: metadata.turnCount,
+            messageCount: metadata.messageCount,
+            title: metadata.title,
+        },
+        costSnapshot: usageSnapshot,
+    };
+    await writeJsonAtomic(path.join(dir, LEGACY_STATE_FILE), state);
+}
+export function getSessionMetadata(sessionId, projectRoot) {
+    const dir = findExistingSessionDir(sessionId, projectRoot);
+    if (!dir)
+        return null;
+    const metadataPath = path.join(dir, METADATA_FILE);
+    try {
+        const raw = fs.readFileSync(metadataPath, "utf8");
+        const parsed = JSON.parse(raw);
+        const normalized = normalizeSessionMetadata(sessionId, parsed);
+        if (metadataNeedsMigration(parsed)) {
+            writeJsonAtomicSync(metadataPath, normalized);
+        }
+        return normalized;
+    }
+    catch {
+        return null;
+    }
+}
+export async function readSessionMetadata(sessionId, projectRoot, defaults = {}) {
+    const metadataPath = getMetadataPath(sessionId, projectRoot);
+    let parsed = null;
+    try {
+        parsed = JSON.parse(await fs.promises.readFile(metadataPath, "utf8"));
+    }
+    catch {
+        parsed = null;
+    }
+    const normalized = normalizeSessionMetadata(sessionId, parsed, defaults);
+    if (!parsed || metadataNeedsMigration(parsed)) {
+        await fs.promises.mkdir(path.dirname(metadataPath), { recursive: true });
+        await writeJsonAtomic(metadataPath, normalized);
+    }
+    return normalized;
+}
+export async function saveSessionState(sessionId, usageSnapshot, metadata, projectRoot) {
+    await withSessionWriteLimit(async () => {
+        const dir = getSessionDir(sessionId, projectRoot);
+        await fs.promises.mkdir(dir, { recursive: true });
+        let existing = {};
+        try {
+            const raw = await fs.promises.readFile(path.join(dir, METADATA_FILE), "utf8");
+            existing = JSON.parse(raw);
+        }
+        catch {
+            existing = {};
+        }
+        const now = new Date().toISOString();
+        const merged = normalizeSessionMetadata(sessionId, {
+            sessionId,
+            projectId: metadata.projectId ?? existing.projectId ?? "",
+            createdAt: metadata.createdAt ?? existing.createdAt ?? now,
+            lastActiveAt: now,
+            model: metadata.model ?? existing.model,
+            agentId: metadata.agentId ?? existing.agentId,
+            cwd: metadata.cwd ?? existing.cwd,
+            turnCount: usageSnapshot.turnCount,
+            messageCount: metadata.messageCount ?? existing.messageCount ?? 0,
+            title: metadata.title ?? existing.title,
+            taskSummary: metadata.taskSummary ?? existing.taskSummary,
+            taskSummaryGeneratedAt: metadata.taskSummaryGeneratedAt ?? existing.taskSummaryGeneratedAt,
+            pinnedAt: metadata.pinnedAt !== undefined ? metadata.pinnedAt : existing.pinnedAt,
+            archivedAt: metadata.archivedAt !== undefined ? metadata.archivedAt : existing.archivedAt,
+            sealedAt: metadata.sealedAt ?? existing.sealedAt,
+            previousSessionId: metadata.previousSessionId ?? existing.previousSessionId,
+            carryoverSummary: metadata.carryoverSummary ?? existing.carryoverSummary,
+            type: metadata.type ?? existing.type,
+            ownerPlatform: metadata.ownerPlatform ?? existing.ownerPlatform,
+            ownerId: metadata.ownerId ?? existing.ownerId,
+            groupKey: metadata.groupKey ?? existing.groupKey,
+            groupName: metadata.groupName ?? existing.groupName,
+            groupPlatform: metadata.groupPlatform ?? existing.groupPlatform,
+            totalInputTokens: usageSnapshot.totalInputTokens,
+            totalOutputTokens: usageSnapshot.totalOutputTokens,
+        });
+        await writeJsonAtomic(path.join(dir, METADATA_FILE), merged);
+        await writeLegacyStateProjection(dir, merged, usageSnapshot);
+    });
+}
+export async function updateSessionMetadata(sessionId, patch, projectRoot) {
+    return withSessionWriteLimit(async () => {
+        const existingDir = findExistingSessionDir(sessionId, projectRoot);
+        const dir = existingDir ?? getSessionDir(sessionId, projectRoot);
+        const metadataPath = path.join(dir, METADATA_FILE);
+        const now = new Date().toISOString();
+        let current;
+        try {
+            const raw = await fs.promises.readFile(metadataPath, "utf8");
+            current = normalizeSessionMetadata(sessionId, JSON.parse(raw));
+        }
+        catch {
+            await fs.promises.mkdir(dir, { recursive: true });
+            current = normalizeSessionMetadata(sessionId, {
+                projectId: patch.projectId ?? "",
+                createdAt: now,
+                lastActiveAt: now,
+                turnCount: 0,
+                messageCount: 0,
+            });
+        }
+        const updated = applyMetadataPatch(current, patch);
+        updated.lastActiveAt = now;
+        await fs.promises.mkdir(dir, { recursive: true });
+        await writeJsonAtomic(metadataPath, updated);
+        return updated;
+    });
+}
+export async function persistTaskSummary(sessionId, projectRoot, summary, generatedAtTurn) {
+    await withSessionWriteLimit(async () => {
+        const current = await readSessionMetadata(sessionId, projectRoot);
+        await writeJsonAtomic(getMetadataPath(sessionId, projectRoot), {
+            ...current,
+            taskSummary: summary,
+            taskSummaryGeneratedAt: generatedAtTurn,
+        });
+    });
+}
+function applyMetadataPatch(current, patch) {
+    const updated = { ...current };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            continue;
+        if (value === null) {
+            delete updated[key];
+        }
+        else {
+            updated[key] = value;
+        }
+    }
+    return normalizeSessionMetadata(String(updated.sessionId ?? current.sessionId), updated);
+}

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

@@ -0,0 +1,9 @@
+export declare const TRANSCRIPT_FILE = "transcript.jsonl";
+export declare const METADATA_FILE = "metadata.json";
+export declare const LEGACY_STATE_FILE = "state.json";
+export declare function sanitizeSessionId(sessionId: string): string;
+export declare function getSessionsRoot(projectRoot: string): string;
+export declare function getSessionDir(sessionId: string, projectRoot: string): string;
+export declare function getMetadataPath(sessionId: string, projectRoot: string): string;
+export declare function getTranscriptPath(sessionId: string, projectRoot: string): string;
+export declare function findExistingSessionDir(sessionId: string, projectRoot: string): string | undefined;

package/dist/runtime/session/session-paths.js

@@ -0,0 +1,27 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getDefaultPathService } from "../infra/default-path-service.js";
+export const TRANSCRIPT_FILE = "transcript.jsonl";
+export const METADATA_FILE = "metadata.json";
+export const LEGACY_STATE_FILE = "state.json";
+export function sanitizeSessionId(sessionId) {
+    return sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+export function getSessionsRoot(projectRoot) {
+    return getDefaultPathService().getProjectSessionsRoot(projectRoot);
+}
+export function getSessionDir(sessionId, projectRoot) {
+    return path.join(getSessionsRoot(projectRoot), sanitizeSessionId(sessionId));
+}
+export function getMetadataPath(sessionId, projectRoot) {
+    return path.join(getSessionDir(sessionId, projectRoot), METADATA_FILE);
+}
+export function getTranscriptPath(sessionId, projectRoot) {
+    return path.join(getSessionDir(sessionId, projectRoot), TRANSCRIPT_FILE);
+}
+export function findExistingSessionDir(sessionId, projectRoot) {
+    const dir = getSessionDir(sessionId, projectRoot);
+    if (fs.existsSync(path.join(dir, METADATA_FILE)))
+        return dir;
+    return undefined;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Compatibility facade for session persistence.
+ *
+ * The implementation lives in focused modules:
+ * - session-transcript-store.ts: append-only transcript JSONL
+ * - session-metadata-store.ts: metadata schema, migration, atomic writes
+ * - session-resume.ts: resume assembly
+ * - session-catalog.ts: list/delete/prune
+ * - session-summary.ts: title and task-summary generation
+ */
+export { appendMessage } from "./session-transcript-store.js";
+export { getSessionMetadata, readSessionMetadata, saveSessionState, updateSessionMetadata, } from "./session-metadata-store.js";
+export { loadSessionForResume } from "./session-resume.js";
+export { deleteSession, listSessions, pruneOldSessions } from "./session-catalog.js";
+export { generateSessionTitle, maybeGenerateTaskSummary, shouldGenerateTaskSummary, } from "./session-summary.js";
+export { SESSION_SCHEMA_VERSION, type MessageDisplayMetadata, type PersistedChatMessage, type PersistedSession, type SessionListEntry, type SessionMetadata, type TaskSummaryDeps, } from "./session-types.js";

package/dist/runtime/session/session-persistence.js

@@ -0,0 +1,16 @@
+/**
+ * Compatibility facade for session persistence.
+ *
+ * The implementation lives in focused modules:
+ * - session-transcript-store.ts: append-only transcript JSONL
+ * - session-metadata-store.ts: metadata schema, migration, atomic writes
+ * - session-resume.ts: resume assembly
+ * - session-catalog.ts: list/delete/prune
+ * - session-summary.ts: title and task-summary generation
+ */
+export { appendMessage } from "./session-transcript-store.js";
+export { getSessionMetadata, readSessionMetadata, saveSessionState, updateSessionMetadata, } from "./session-metadata-store.js";
+export { loadSessionForResume } from "./session-resume.js";
+export { deleteSession, listSessions, pruneOldSessions } from "./session-catalog.js";
+export { generateSessionTitle, maybeGenerateTaskSummary, shouldGenerateTaskSummary, } from "./session-summary.js";
+export { SESSION_SCHEMA_VERSION, } from "./session-types.js";

package/dist/runtime/session/session-persistence.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/session/session-persistence.test.js

@@ -0,0 +1,237 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { appendMessage, getSessionMetadata, listSessions, loadSessionForResume, saveSessionState, updateSessionMetadata, } from "./session-persistence.js";
+const roots = [];
+function makeProjectRoot() {
+    const root = mkdtempSync(join(tmpdir(), "qlogicagent-session-persistence-"));
+    roots.push(root);
+    return root;
+}
+afterEach(() => {
+    for (const root of roots.splice(0)) {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+describe("session persistence", () => {
+    it("keeps flat metadata.json while writing legacy state.json projection", async () => {
+        const projectRoot = makeProjectRoot();
+        const sessionId = "compat-session";
+        await saveSessionState(sessionId, {
+            sessionId,
+            modelUsage: {
+                "test-model": {
+                    inputTokens: 12,
+                    outputTokens: 34,
+                    cacheRead: 0,
+                    cacheCreation: 0,
+                    mediaCalls: 0,
+                    mediaDurationSeconds: 0,
+                    mediaCharacters: 0,
+                },
+            },
+            totalInputTokens: 12,
+            totalOutputTokens: 34,
+            turnCount: 2,
+            lastSavedAt: 1780000000000,
+        }, {
+            model: "test-model",
+            cwd: projectRoot,
+            projectId: "project-a",
+            messageCount: 4,
+        }, projectRoot);
+        const sessionDir = join(projectRoot, ".qlogicagent", "sessions", sessionId);
+        const metadata = JSON.parse(readFileSync(join(sessionDir, "metadata.json"), "utf8"));
+        const state = JSON.parse(readFileSync(join(sessionDir, "state.json"), "utf8"));
+        expect(metadata.metadata).toBeUndefined();
+        expect(metadata.sessionId).toBe(sessionId);
+        expect(metadata.turnCount).toBe(2);
+        expect(state.metadata.sessionId).toBe(sessionId);
+        expect(state.metadata.createdAt).toEqual(expect.any(Number));
+        expect(state.metadata.lastActiveAt).toEqual(expect.any(Number));
+        expect(state.metadata.turnCount).toBe(2);
+        expect(state.costSnapshot.sessionId).toBe(sessionId);
+        expect(state.costSnapshot.totalInputTokens).toBe(12);
+        expect(state.costSnapshot.totalOutputTokens).toBe(34);
+        expect(state.costSnapshot.turnCount).toBe(2);
+    });
+    it("lists carryover summary and defaults personal session type for wire clients", async () => {
+        const projectRoot = makeProjectRoot();
+        const sessionId = "carryover-session";
+        await saveSessionState(sessionId, {
+            sessionId,
+            modelUsage: {},
+            totalInputTokens: 0,
+            totalOutputTokens: 0,
+            turnCount: 1,
+            lastSavedAt: 1780000000000,
+        }, {
+            projectId: "project-carryover",
+            carryoverSummary: "previous work summary",
+            previousSessionId: "parent-session",
+            messageCount: 1,
+        }, projectRoot);
+        const [entry] = await listSessions(10, projectRoot);
+        expect(entry.sessionId).toBe(sessionId);
+        expect(entry.type).toBe("personal");
+        expect(entry.previousSessionId).toBe("parent-session");
+        expect(entry.carryoverSummary).toBe("previous work summary");
+    });
+    it("persists the owner platform for automatically bound personal IM sessions", async () => {
+        const projectRoot = makeProjectRoot();
+        const sessionId = "wecom-personal-session";
+        await saveSessionState(sessionId, {
+            sessionId,
+            modelUsage: {},
+            totalInputTokens: 0,
+            totalOutputTokens: 0,
+            turnCount: 1,
+            lastSavedAt: 1780000000000,
+        }, {
+            projectId: "project-wecom",
+            type: "personal",
+            ownerPlatform: "wecom",
+            ownerId: "wecom-user-1",
+            messageCount: 1,
+        }, projectRoot);
+        const metadata = getSessionMetadata(sessionId, projectRoot);
+        expect(metadata?.ownerPlatform).toBe("wecom");
+        expect(metadata?.ownerId).toBe("wecom-user-1");
+    });
+    it("migrates legacy metadata files to the current session schema", async () => {
+        const projectRoot = makeProjectRoot();
+        const sessionId = "legacy-metadata-session";
+        const sessionDir = join(projectRoot, ".qlogicagent", "sessions", sessionId);
+        mkdirSync(sessionDir, { recursive: true });
+        writeFileSync(join(sessionDir, "metadata.json"), JSON.stringify({
+            sessionId,
+            projectId: "project-legacy",
+            createdAt: "2026-06-01T00:00:00.000Z",
+            lastActiveAt: "2026-06-01T00:00:00.000Z",
+            turnCount: 1,
+            messageCount: 2,
+        }, null, 2), "utf8");
+        writeFileSync(join(sessionDir, "transcript.jsonl"), JSON.stringify({
+            role: "user",
+            content: "hello",
+            ts: Date.now(),
+        }) + "\n", "utf8");
+        const resumed = await loadSessionForResume(sessionId, projectRoot);
+        const metadata = JSON.parse(readFileSync(join(sessionDir, "metadata.json"), "utf8"));
+        expect(resumed?.metadata.schemaVersion).toBe(1);
+        expect(metadata.schemaVersion).toBe(1);
+        expect(metadata.type).toBe("personal");
+        expect(metadata.messageCount).toBe(2);
+    });
+    it("serializes concurrent appends for the same session in call order", async () => {
+        const projectRoot = makeProjectRoot();
+        const sessionId = "ordered-append-session";
+        const writes = Array.from({ length: 24 }, (_, i) => appendMessage(sessionId, { role: "assistant", content: `message-${i}` }, projectRoot, `turn-${i}`));
+        await Promise.all(writes);
+        const raw = readFileSync(join(projectRoot, ".qlogicagent", "sessions", sessionId, "transcript.jsonl"), "utf8");
+        const contents = raw.trim().split("\n").map((line) => JSON.parse(line).content);
+        expect(contents).toEqual(Array.from({ length: 24 }, (_, i) => `message-${i}`));
+    });
+    it("keeps per-message usage for display history without feeding it back to resume context", async () => {
+        const projectRoot = makeProjectRoot();
+        const sessionId = "usage-session";
+        await appendMessage(sessionId, { role: "assistant", content: "done" }, projectRoot, "turn-usage", { usage: { inputTokens: 105, outputTokens: 61, cacheRead: 11648 } });
+        const display = await loadSessionForResume(sessionId, projectRoot, { includeDisplayMetadata: true });
+        expect(display?.messages[0]).toMatchObject({
+            role: "assistant",
+            content: "done",
+            turnId: "turn-usage",
+            usage: { inputTokens: 105, outputTokens: 61, cacheRead: 11648 },
+        });
+        expect(display?.messages[0]?.timestamp).toEqual(expect.any(String));
+        const resume = await loadSessionForResume(sessionId, projectRoot);
+        expect(resume?.messages[0]).toEqual({ role: "assistant", content: "done" });
+    });
+    it("keeps external display identity only in display history", async () => {
+        const projectRoot = makeProjectRoot();
+        const sessionId = "im-display-session";
+        await appendMessage(sessionId, { role: "user", content: "from weixin" }, projectRoot, "turn-im", {
+            displayMetadata: {
+                messageId: "openclaw-weixin:msg-1",
+                platform: "weixin",
+                sourceChannel: "weixin",
+                source: "weixin",
+                chatId: "wx-chat-1",
+                userId: "wx-user-1",
+                userName: "Alice",
+            },
+        });
+        const display = await loadSessionForResume(sessionId, projectRoot, { includeDisplayMetadata: true });
+        expect(display?.messages[0]).toMatchObject({
+            role: "user",
+            content: "from weixin",
+            turnId: "turn-im",
+            displayMetadata: {
+                messageId: "openclaw-weixin:msg-1",
+                platform: "weixin",
+                sourceChannel: "weixin",
+                source: "weixin",
+                chatId: "wx-chat-1",
+                userId: "wx-user-1",
+                userName: "Alice",
+            },
+        });
+        const resume = await loadSessionForResume(sessionId, projectRoot);
+        expect(resume?.messages[0]).toEqual({ role: "user", content: "from weixin" });
+    });
+    it("preserves media fields for display history and resume context", async () => {
+        const projectRoot = makeProjectRoot();
+        const sessionId = "media-session";
+        await appendMessage(sessionId, {
+            role: "assistant",
+            content: "generated image",
+            imageUrls: ["data:image/png;base64,abc123"],
+            videoUrls: ["file:///tmp/demo.mp4"],
+            audioUrls: ["file:///tmp/demo.wav"],
+            fileIds: [{ id: "file-1", mimeType: "application/pdf", size: 42 }],
+            imageDetail: "high",
+        }, projectRoot, "turn-media");
+        const display = await loadSessionForResume(sessionId, projectRoot, { includeDisplayMetadata: true });
+        expect(display?.messages[0]).toMatchObject({
+            role: "assistant",
+            content: "generated image",
+            turnId: "turn-media",
+            imageUrls: ["data:image/png;base64,abc123"],
+            videoUrls: ["file:///tmp/demo.mp4"],
+            audioUrls: ["file:///tmp/demo.wav"],
+            fileIds: [{ id: "file-1", mimeType: "application/pdf", size: 42 }],
+            imageDetail: "high",
+        });
+        const resume = await loadSessionForResume(sessionId, projectRoot);
+        expect(resume?.messages[0]).toMatchObject({
+            role: "assistant",
+            content: "generated image",
+            imageUrls: ["data:image/png;base64,abc123"],
+            videoUrls: ["file:///tmp/demo.mp4"],
+            audioUrls: ["file:///tmp/demo.wav"],
+            fileIds: [{ id: "file-1", mimeType: "application/pdf", size: 42 }],
+            imageDetail: "high",
+        });
+        expect(resume?.messages[0]).not.toHaveProperty("turnId");
+    });
+    it("archives many sessions concurrently without losing updates or deadlocking", async () => {
+        const projectRoot = makeProjectRoot();
+        const ids = Array.from({ length: 18 }, (_, i) => `concurrent-session-${i}`);
+        for (const sessionId of ids) {
+            await updateSessionMetadata(sessionId, { projectId: "p", title: sessionId }, projectRoot);
+        }
+        const archivedAt = "2026-06-04T00:00:00.000Z";
+        // Fire all archive updates at once. The fs-write concurrency cap bounds how
+        // many run in parallel, but every one must still resolve (no deadlock) and
+        // persist (no lost writes). This is the regression guard for the batch-archive
+        // hang that wedged the whole stdio RPC channel.
+        const results = await Promise.all(ids.map((id) => updateSessionMetadata(id, { archivedAt }, projectRoot)));
+        expect(results).toHaveLength(ids.length);
+        expect(results.every((r) => r?.archivedAt === archivedAt)).toBe(true);
+        for (const id of ids) {
+            expect(getSessionMetadata(id, projectRoot)?.archivedAt).toBe(archivedAt);
+        }
+    });
+});

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

@@ -0,0 +1,4 @@
+import type { PersistedSession } from "./session-types.js";
+export declare function loadSessionForResume(sessionId: string, projectRoot: string, options?: {
+    includeDisplayMetadata?: boolean;
+}): Promise<PersistedSession | null>;