memax-cli 0.1.0-alpha.35 → 0.1.0-alpha.37

package/dist/commands/agent-sessions.d.ts

@@ -1,3 +1,4 @@
+import type { AgentSession, SessionSyncPlanAction } from "memax-sdk";
 interface AgentSessionLocation {
     agent: string;
     path: string;
@@ -17,6 +18,13 @@ interface SessionProjectContext {
     projectRoot?: string;
 }
 export declare function hashPortableSessionContent(agent: string, content: Buffer, projectRoot?: string): string;
+export declare function computeSessionSyncHash(agent: string, scope: string, content: Buffer, currentProjectRootPath: string): string;
+export declare function isLegacyGlobalSessionShadowed(action: SessionSyncPlanAction, projectScopedKeys: Set<string>): boolean;
+interface ShadowedGlobalSessionPair {
+    global: AgentSession;
+    project: AgentSession;
+}
+export declare function findShadowedGlobalSessions(sessions: AgentSession[]): ShadowedGlobalSessionPair[];
 export declare function computeSessionProjectContext(agent: string, path: string, fallbackProjectRoot?: string | null): SessionProjectContext;
 export declare function materializeAgentSessionContent(agent: string, content: Buffer, options: {
     scope: string;
@@ -28,7 +36,12 @@ export declare function syncAgentSessionsCommand(options?: {
     pull?: boolean;
 }): Promise<void>;
 export declare function listAgentSessionsCommand(): Promise<void>;
+export declare function listDeletedAgentSessionsCommand(): Promise<void>;
+export declare function restoreDeletedAgentSessionsCommand(): Promise<void>;
 export declare function deleteAgentSessionsCommand(): Promise<void>;
+export declare function cleanupAgentSessionsCommand(options?: {
+    yes?: boolean;
+}): Promise<void>;
 export declare function doctorAgentSessionsCommand(): Promise<void>;
 export declare function resolveAgentSessionWritePath(agent: string, filePath: string, scope: string, options?: {
     cwd?: string;

package/dist/commands/agent-sessions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-sessions.d.ts","sourceRoot":"","sources":["../../src/commands/agent-sessions.ts"],"names":[],"mappings":"AA8BA,UAAU,oBAAoB;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,qBAAqB;IAC7B,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,mBAAmB,GAAG,YAAY,CAAC;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,UAAU,qBAAqB;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA6GD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAGR;AAoDD,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,GAClC,qBAAqB,CAYvB;AAmBD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB,EAAE,MAAM,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB,GACA,MAAM,CAyBR;AAED,wBAAsB,wBAAwB,CAC5C,OAAO,GAAE;IACP,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;CACX,GACL,OAAO,CAAC,IAAI,CAAC,CA8Zf;AAED,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC,CA0B9D;AAED,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC,CAmHhE;AAED,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC,CA8EhE;AAsID,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC5B,GACL,MAAM,GAAG,IAAI,CAiEf;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CAC3C,GACL,qBAAqB,CAuBvB"}
+{"version":3,"file":"agent-sessions.d.ts","sourceRoot":"","sources":["../../src/commands/agent-sessions.ts"],"names":[],"mappings":"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"}

package/dist/commands/agent-sessions.js

@@ -1,13 +1,15 @@
 import chalk from "chalk";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
 import { homedir } from "node:os";
 import { getClient } from "../lib/client.js";
 import { getProjectScope, resolveClaudeProjectPath, resolveClaudeProjectFolder, resolveProjectRootPath, resolveProjectScope, normalizeFilePath, } from "../lib/project-context.js";
 import { getOrCreateDeviceID, loadConfig } from "../lib/config.js";
 import { ask, confirmDefault } from "../lib/prompt.js";
+import { moveFileToTrash } from "../lib/trash.js";
 const PROJECT_ROOT_PLACEHOLDER = "__MEMAX_PROJECT_ROOT__";
+const PORTABLE_SESSION_AGENTS = new Set(["claude-code", "codex", "gemini"]);
 function isWithinRoot(candidate, root) {
     return candidate === root || candidate.startsWith(`${root}/`);
 }
@@ -93,6 +95,61 @@ export function hashPortableSessionContent(agent, content, projectRoot) {
     const canonical = canonicalizeSessionContent(agent, content, projectRoot);
     return createHash("sha256").update(canonical).digest("hex");
 }
+export function computeSessionSyncHash(agent, scope, content, currentProjectRootPath) {
+    return hashPortableSessionContent(agent, content, scope.startsWith("project:") ? currentProjectRootPath : undefined);
+}
+export function isLegacyGlobalSessionShadowed(action, projectScopedKeys) {
+    if (action.scope !== "global")
+        return false;
+    if (action.reason !== "cloud_only" &&
+        action.reason !== "deleted_everywhere") {
+        return false;
+    }
+    if (!PORTABLE_SESSION_AGENTS.has(action.agent))
+        return false;
+    if (action.agent === "codex" &&
+        normalizeFilePath(action.file_path) === "history.jsonl") {
+        return false;
+    }
+    return projectScopedKeys.has(`${action.agent}|${normalizeFilePath(action.file_path)}`);
+}
+export function findShadowedGlobalSessions(sessions) {
+    const projectScopedByKey = new Map();
+    for (const session of sessions) {
+        if (!PORTABLE_SESSION_AGENTS.has(session.agent))
+            continue;
+        if (!session.scope.startsWith("project:"))
+            continue;
+        const normalized = normalizeFilePath(session.file_path);
+        if (session.agent === "codex" && normalized === "history.jsonl")
+            continue;
+        const key = `${session.agent}|${normalized}`;
+        const group = projectScopedByKey.get(key) ?? [];
+        group.push(session);
+        projectScopedByKey.set(key, group);
+    }
+    const pairs = [];
+    for (const session of sessions) {
+        if (!PORTABLE_SESSION_AGENTS.has(session.agent))
+            continue;
+        if (session.scope !== "global")
+            continue;
+        const normalized = normalizeFilePath(session.file_path);
+        if (session.agent === "codex" && normalized === "history.jsonl")
+            continue;
+        const siblings = projectScopedByKey.get(`${session.agent}|${normalized}`);
+        if (!siblings)
+            continue;
+        for (const sibling of siblings) {
+            pairs.push({ global: session, project: sibling });
+        }
+    }
+    return pairs;
+}
+function computeDownloadedPortableHash(agent, content) {
+    const projectRoot = readStructuredSessionRootFromContent(agent, content);
+    return hashPortableSessionContent(agent, content, projectRoot ?? undefined);
+}
 function readStructuredSessionRootFromContent(agent, content) {
     try {
         const raw = content.toString("utf-8");
@@ -232,6 +289,10 @@ export async function syncAgentSessionsCommand(options = {}) {
             return false;
         return true;
     });
+    const projectScopedKeys = new Set(actions
+        .filter((action) => action.scope.startsWith("project:"))
+        .map((action) => `${action.agent}|${normalizeFilePath(action.file_path)}`));
+    actions = actions.filter((action) => !isLegacyGlobalSessionShadowed(action, projectScopedKeys));
     const localByKey = new Map();
     for (const session of localSessions) {
         localByKey.set(`${session.loc.agent}|${session.loc.filePath}|${session.loc.scope}`, session);
@@ -254,6 +315,7 @@ export async function syncAgentSessionsCommand(options = {}) {
     let pushed = 0;
     let pulled = 0;
     let deletedLocal = 0;
+    let reconciled = 0;
     let unchanged = 0;
     let skipped = 0;
     let errors = 0;
@@ -343,17 +405,18 @@ export async function syncAgentSessionsCommand(options = {}) {
                     const session = await getClient().agentSessions.get(action.session_id);
                     const bytes = await downloadAgentSession(action.session_id);
                     mkdirSync(dirname(writePath), { recursive: true });
-                    writeFileSync(writePath, materializeAgentSessionContent(action.agent, bytes, {
+                    const materialized = materializeAgentSessionContent(action.agent, bytes, {
                         scope: action.scope,
                         currentProjectRootPath,
                         writePath,
-                    }));
+                    });
+                    writeFileSync(writePath, materialized);
                     if (action.version) {
                         ackSessions.push({
                             agent: action.agent,
                             file_path: action.file_path,
                             scope: action.scope,
-                            content_hash: session.content_hash,
+                            content_hash: computeSessionSyncHash(action.agent, action.scope, materialized, currentProjectRootPath),
                             version: action.version,
                             local_path: writePath,
                         });
@@ -368,10 +431,65 @@ export async function syncAgentSessionsCommand(options = {}) {
                 continue;
             }
             if (action.action === "delete_local") {
+                if (isLegacyGlobalSessionShadowed(action, projectScopedKeys)) {
+                    if (action.version) {
+                        ackSessions.push({
+                            agent: action.agent,
+                            file_path: action.file_path,
+                            scope: action.scope,
+                            version: action.version,
+                            deleted: true,
+                        });
+                    }
+                    console.log(chalk.gray(`    = ${action.file_path}`), chalk.gray("legacy global duplicate removed"));
+                    reconciled++;
+                    continue;
+                }
+                if (!options.pull) {
+                    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+                        console.log(chalk.yellow(`    - ${action.file_path}`), chalk.gray("cloud deleted this session artifact — skipped in non-interactive mode"));
+                        skipped++;
+                        continue;
+                    }
+                    const resolution = await promptSessionCloudDeletion(action.file_path);
+                    if (resolution === "skip") {
+                        console.log(chalk.gray(`    - ${action.file_path}`), chalk.gray("skipped"));
+                        skipped++;
+                        continue;
+                    }
+                    if (resolution === "local") {
+                        const local = localByKey.get(key);
+                        if (!local) {
+                            console.log(chalk.yellow(`    - ${action.file_path}`), chalk.gray("local file missing — skipped"));
+                            skipped++;
+                            continue;
+                        }
+                        try {
+                            const fileRef = await uploadLocalFile(local.loc.path, local.content);
+                            await getClient().agentSessions.upsert({
+                                agent: action.agent,
+                                file_path: action.file_path,
+                                scope: action.scope,
+                                session_type: local.loc.sessionType,
+                                content_hash: local.hash,
+                                device_id: deviceID,
+                                local_path: local.loc.path,
+                                file_ref: fileRef,
+                            });
+                            console.log(chalk.green(`    ↑ ${action.file_path}`), chalk.gray("kept local and restored to cloud"));
+                            pushed++;
+                        }
+                        catch (err) {
+                            console.log(chalk.red(`    ✗ ${action.file_path}`), chalk.gray(err.message));
+                            errors++;
+                        }
+                        continue;
+                    }
+                }
                 try {
                     const writePath = resolveWritePath(action.agent, action.file_path, action.scope);
                     if (writePath && existsSync(writePath)) {
-                        rmSync(writePath);
+                        moveFileToTrash(writePath, "agent-sessions");
                     }
                     if (action.version) {
                         ackSessions.push({
@@ -383,7 +501,7 @@ export async function syncAgentSessionsCommand(options = {}) {
                             deleted: true,
                         });
                     }
-                    console.log(chalk.yellow(`    - ${action.file_path}`), chalk.gray("deleted locally (cloud removed everywhere)"));
+                    console.log(chalk.yellow(`    - ${action.file_path}`), chalk.gray("deleted locally (moved to Memax trash)"));
                     deletedLocal++;
                 }
                 catch (err) {
@@ -392,6 +510,11 @@ export async function syncAgentSessionsCommand(options = {}) {
                 }
                 continue;
             }
+            if (!process.stdin.isTTY || !process.stdout.isTTY) {
+                console.log(chalk.yellow(`    - ${action.file_path}`), chalk.gray("conflict skipped in non-interactive mode"));
+                skipped++;
+                continue;
+            }
             const resolution = await promptSessionConflict(action.file_path);
             if (resolution === "local") {
                 const local = localByKey.get(key);
@@ -429,17 +552,18 @@ export async function syncAgentSessionsCommand(options = {}) {
                     const session = await getClient().agentSessions.get(action.session_id);
                     const bytes = await downloadAgentSession(action.session_id);
                     mkdirSync(dirname(writePath), { recursive: true });
-                    writeFileSync(writePath, materializeAgentSessionContent(action.agent, bytes, {
+                    const materialized = materializeAgentSessionContent(action.agent, bytes, {
                         scope: action.scope,
                         currentProjectRootPath,
                         writePath,
-                    }));
+                    });
+                    writeFileSync(writePath, materialized);
                     if (action.version) {
                         ackSessions.push({
                             agent: action.agent,
                             file_path: action.file_path,
                             scope: action.scope,
-                            content_hash: session.content_hash,
+                            content_hash: computeSessionSyncHash(action.agent, action.scope, materialized, currentProjectRootPath),
                             version: action.version,
                             local_path: writePath,
                         });
@@ -476,6 +600,8 @@ export async function syncAgentSessionsCommand(options = {}) {
         parts.push(`${pulled} restored`);
     if (deletedLocal > 0)
         parts.push(`${deletedLocal} deleted locally`);
+    if (reconciled > 0)
+        parts.push(`${reconciled} reconciled`);
     if (unchanged > 0)
         parts.push(`${unchanged} unchanged`);
     if (skipped > 0)
@@ -510,6 +636,120 @@ export async function listAgentSessionsCommand() {
         console.error(chalk.red(`  Failed to fetch session artifacts: ${err.message}\n`));
     }
 }
+export async function listDeletedAgentSessionsCommand() {
+    try {
+        const result = await getClient().agentSessions.listDeleted();
+        const sessions = result.sessions;
+        if (sessions.length === 0) {
+            console.log(chalk.gray("  No recoverable deleted session artifacts.\n"));
+            return;
+        }
+        console.log(chalk.bold("\n  Recoverable Deleted Session Artifacts\n"));
+        for (const [index, session] of sessions.entries()) {
+            const scopeTag = session.scope === "global"
+                ? chalk.dim("global")
+                : chalk.dim(session.scope.replace(/^project:/, ""));
+            console.log(`  ${chalk.bold(String(index + 1).padStart(2, " "))}. ${chalk.cyan(formatAgentName(session.agent))} ${session.file_path} ${scopeTag}`);
+            console.log(chalk.gray(`      deleted ${formatAge(session.deleted_at)} · recoverable until ${session.content_expires_at ? new Date(session.content_expires_at).toLocaleString() : "expired"}`));
+        }
+        console.log();
+    }
+    catch (err) {
+        console.error(chalk.red(`  Failed to fetch deleted session artifacts: ${err.message}\n`));
+    }
+}
+export async function restoreDeletedAgentSessionsCommand() {
+    let deleted;
+    try {
+        deleted = await getClient().agentSessions.listDeleted();
+    }
+    catch (err) {
+        console.error(chalk.red(`  Failed to fetch deleted session artifacts: ${err.message}\n`));
+        return;
+    }
+    if (deleted.sessions.length === 0) {
+        console.log(chalk.gray("  No recoverable deleted session artifacts.\n"));
+        return;
+    }
+    console.log(chalk.bold("\n  Recover Deleted Session Artifacts\n"));
+    deleted.sessions.forEach((session, index) => {
+        const scopeTag = session.scope === "global"
+            ? chalk.dim("global")
+            : chalk.dim(session.scope.replace(/^project:/, ""));
+        console.log(`  ${chalk.dim(`${index + 1}.`)} ${chalk.cyan(formatAgentName(session.agent))} ${session.file_path} ${scopeTag}`);
+    });
+    console.log();
+    const answer = await ask("  Select session artifacts to restore (comma-separated numbers, or 'q' to quit): ");
+    if (!answer || answer.trim().toLowerCase() === "q") {
+        console.log(chalk.gray("  Cancelled.\n"));
+        return;
+    }
+    const indexes = answer
+        .split(",")
+        .map((part) => Number.parseInt(part.trim(), 10))
+        .filter((idx) => Number.isInteger(idx) && idx >= 1 && idx <= deleted.sessions.length);
+    if (indexes.length === 0) {
+        console.log(chalk.gray("  No valid selection.\n"));
+        return;
+    }
+    const cwd = process.cwd();
+    const deviceID = getOrCreateDeviceID();
+    const currentProjectScope = getProjectScope(cwd);
+    const currentProjectRootPath = resolveProjectRootPath(cwd) ?? cwd;
+    let restored = 0;
+    for (const index of indexes) {
+        const sessionInfo = deleted.sessions[index - 1];
+        try {
+            const writePath = resolveAgentSessionWritePath(sessionInfo.agent, sessionInfo.file_path, sessionInfo.scope, {
+                cwd,
+                home: homedir(),
+                currentProjectScope,
+            });
+            const session = await getClient().agentSessions.restore({
+                agent: sessionInfo.agent,
+                file_path: sessionInfo.file_path,
+                scope: sessionInfo.scope,
+                device_id: deviceID,
+                local_path: writePath ?? undefined,
+            });
+            if (writePath && !existsSync(writePath)) {
+                const bytes = await downloadAgentSession(session.id);
+                mkdirSync(dirname(writePath), { recursive: true });
+                const materialized = materializeAgentSessionContent(session.agent, bytes, {
+                    scope: session.scope,
+                    currentProjectRootPath,
+                    writePath,
+                });
+                writeFileSync(writePath, materialized);
+                await getClient().agentSessions.ack({
+                    device_id: deviceID,
+                    sessions: [
+                        {
+                            agent: session.agent,
+                            file_path: session.file_path,
+                            scope: session.scope,
+                            content_hash: computeSessionSyncHash(session.agent, session.scope, materialized, currentProjectRootPath),
+                            version: session.version,
+                            local_path: writePath,
+                        },
+                    ],
+                });
+                console.log(chalk.green(`    ✓ ${session.file_path}`), chalk.gray("restored to cloud and local machine"));
+            }
+            else if (writePath && existsSync(writePath)) {
+                console.log(chalk.yellow(`    - ${session.file_path}`), chalk.gray("restored to cloud; local file already exists"));
+            }
+            else {
+                console.log(chalk.yellow(`    - ${session.file_path}`), chalk.gray("restored to cloud; no safe local path on this machine"));
+            }
+            restored++;
+        }
+        catch (err) {
+            console.log(chalk.red(`    ✗ ${sessionInfo.file_path}`), chalk.gray(err.message));
+        }
+    }
+    console.log(chalk.gray(`\n  ${restored} session artifact${restored === 1 ? "" : "s"} restored.\n`));
+}
 export async function deleteAgentSessionsCommand() {
     let sessions;
     try {
@@ -566,13 +806,13 @@ export async function deleteAgentSessionsCommand() {
                     local_path: localPath ?? undefined,
                 });
                 if (localPath && existsSync(localPath)) {
-                    rmSync(localPath);
+                    moveFileToTrash(localPath, "agent-sessions");
                 }
             }
             else {
                 await getClient().agentSessions.delete(session.id);
                 if (localPath && existsSync(localPath)) {
-                    rmSync(localPath);
+                    moveFileToTrash(localPath, "agent-sessions");
                 }
                 await getClient().agentSessions.ack({
                     device_id: deviceID,
@@ -596,6 +836,94 @@ export async function deleteAgentSessionsCommand() {
     }
     console.log();
 }
+export async function cleanupAgentSessionsCommand(options) {
+    let sessions;
+    try {
+        sessions = (await getClient().agentSessions.list()).sessions;
+    }
+    catch (err) {
+        console.error(chalk.red(`  Failed to fetch session artifacts: ${err.message}\n`));
+        return;
+    }
+    const pairs = findShadowedGlobalSessions(sessions);
+    if (pairs.length === 0) {
+        console.log(chalk.gray("  No legacy global session duplicates found.\n"));
+        return;
+    }
+    const safePairs = [];
+    const divergedPairs = [];
+    for (const pair of pairs) {
+        if (pair.global.content_hash === pair.project.content_hash) {
+            safePairs.push(pair);
+            continue;
+        }
+        try {
+            const [globalBytes, projectBytes] = await Promise.all([
+                downloadAgentSession(pair.global.id),
+                downloadAgentSession(pair.project.id),
+            ]);
+            if (computeDownloadedPortableHash(pair.global.agent, globalBytes) ===
+                computeDownloadedPortableHash(pair.project.agent, projectBytes)) {
+                safePairs.push(pair);
+            }
+            else {
+                divergedPairs.push(pair);
+            }
+        }
+        catch {
+            divergedPairs.push(pair);
+        }
+    }
+    console.log(chalk.bold("\n  Session Duplicate Cleanup\n"));
+    if (safePairs.length > 0) {
+        console.log(chalk.white("  Safe To Remove"));
+        for (const pair of safePairs) {
+            console.log(`    ${chalk.cyan(formatAgentName(pair.global.agent))}  ${pair.global.file_path}`);
+            console.log(`      ${chalk.gray("delete legacy global copy; project-scoped copy remains")}`);
+        }
+        console.log();
+    }
+    if (divergedPairs.length > 0) {
+        console.log(chalk.yellow("  Needs Manual Review"));
+        for (const pair of divergedPairs) {
+            console.log(`    ${chalk.yellow(formatAgentName(pair.global.agent))}  ${pair.global.file_path}`);
+            console.log(`      ${chalk.gray(`global hash ${pair.global.content_hash.slice(0, 8)}… differs from project ${pair.project.scope.replace(/^project:/, "")} hash ${pair.project.content_hash.slice(0, 8)}…`)}`);
+        }
+        console.log();
+    }
+    if (safePairs.length === 0) {
+        console.log(chalk.gray("  No identical legacy global duplicates can be removed safely.\n"));
+        return;
+    }
+    if (!options?.yes) {
+        const proceed = await confirmDefault(`  Delete ${safePairs.length} safe global duplicate${safePairs.length === 1 ? "" : "s"} from cloud? [Y/n] `);
+        if (!proceed) {
+            console.log(chalk.gray("  Cancelled.\n"));
+            return;
+        }
+    }
+    let deleted = 0;
+    let errors = 0;
+    for (const pair of safePairs) {
+        try {
+            await getClient().agentSessions.delete(pair.global.id);
+            console.log(chalk.green(`    ✓ ${pair.global.file_path}`), chalk.gray("deleted legacy global copy"));
+            deleted++;
+        }
+        catch (err) {
+            console.log(chalk.red(`    ✗ ${pair.global.file_path}`), chalk.gray(err.message));
+            errors++;
+        }
+    }
+    const summary = [];
+    if (deleted > 0)
+        summary.push(`${deleted} deleted`);
+    if (divergedPairs.length > 0)
+        summary.push(`${divergedPairs.length} need review`);
+    if (errors > 0)
+        summary.push(`${errors} errors`);
+    console.log(chalk.bold(`\n  Done: ${summary.join(", ")}\n`));
+}
 export async function doctorAgentSessionsCommand() {
     const cwd = process.cwd();
     const project = resolveProjectScope(cwd);
@@ -854,6 +1182,15 @@ async function promptSessionConflict(filePath) {
         return "cloud";
     return "skip";
 }
+async function promptSessionCloudDeletion(filePath) {
+    const answer = await ask(`    ${filePath} was deleted in cloud. [d]elete local, [k]eep local and restore cloud, or [s]kip? `);
+    const normalized = answer.trim().toLowerCase();
+    if (normalized === "d")
+        return "delete";
+    if (normalized === "k")
+        return "local";
+    return "skip";
+}
 function readProjectRootMarker(path) {
     if (!existsSync(path))
         return null;
@@ -933,6 +1270,17 @@ function formatBytes(size) {
         return `${(size / 1024).toFixed(1)} KB`;
     return `${(size / (1024 * 1024)).toFixed(1)} MB`;
 }
+function formatAge(dateStr) {
+    const ms = Date.now() - new Date(dateStr).getTime();
+    const mins = Math.floor(ms / 60000);
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
 function basenameSafe(path) {
     return normalizeFilePath(path).split("/").pop() ?? "artifact";
 }