aimux-cli 0.1.15 → 0.1.18

package/dist/main.js

@@ -5,18 +5,21 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { Multiplexer } from "./multiplexer/index.js";
 import { llmCompact } from "./context/compactor.js";
-import { initProject } from "./config.js";
-import { initPaths, getHistoryDir, getGraveyardPath, getStatePath, getContextDir, getProjectId, getProjectStateDirFor, } from "./paths.js";
+import { initProject, loadConfig } from "./config.js";
+import { initPaths, getHistoryDir, getContextDir, getProjectId, getRepoRoot, getDaemonLogPath, getProjectLogPath, getProjectStateDirFor, getRuntimeTopologyPath, } from "./paths.js";
 import { loadTeamConfig, saveTeamConfig, getDefaultTeamConfig } from "./team.js";
-import { createWorktree, findMainRepo, listWorktrees } from "./worktree.js";
+import { findMainRepo, listWorktrees } from "./worktree.js";
 import { TmuxRuntimeManager } from "./tmux/runtime-manager.js";
 import { buildTmuxDoctorReport, renderTmuxDoctorReport, renderTmuxRepairResult, repairTmuxRuntime, } from "./tmux/doctor.js";
-import { loadMetadataEndpoint, resolveProjectServiceEndpoint as resolveStoredProjectServiceEndpoint, updateSessionMetadata, clearSessionLogs, removeMetadataEndpoint, } from "./metadata-store.js";
+import { loadMetadataEndpoint, resolveProjectServiceEndpoint as resolveStoredProjectServiceEndpoint, updateSessionMetadata, clearSessionLogs, loadMetadataState, removeMetadataEndpoint, } from "./metadata-store.js";
+import { contextualizeAlertInput, metadataDisplayContext } from "./alert-display.js";
 import { AgentTracker } from "./agent-tracker.js";
-import { AimuxDaemon, ensureDaemonRunning, ensureProjectService, loadDaemonInfo, loadDaemonState, projectServiceStatus, requestDaemonJson, stopDaemon, stopProjectService, } from "./daemon.js";
+import { AimuxDaemon, ensureDaemonRunning, ensureProjectService, getDaemonHost, getDaemonPort, loadDaemonInfo, loadDaemonState, projectServiceStatus, requestDaemonJson, stopDaemon, stopProjectService, } from "./daemon.js";
 import { getProjectServiceManifest, manifestsMatch } from "./project-service-manifest.js";
 import { createThread, listThreadSummaries, markThreadSeen, readMessages, readThread, setThreadStatus, } from "./threads.js";
 import { sendDirectMessage, sendThreadMessage } from "./orchestration.js";
+import { runLoginFlow } from "./login-flow.js";
+import { clearCredentials, loadCredentials, setRemoteEnabled } from "./credentials.js";
 import { acceptHandoff, approveReview, acceptTask, assignTask, blockTask, completeHandoff, completeTask, reopenTask, requestTaskChanges, sendHandoff, } from "./orchestration-actions.js";
 import { readAllTasks, readTask } from "./tasks.js";
 import { clearNotifications, listNotifications, markNotificationsRead, upsertNotification, unreadNotificationCount, } from "./notifications.js";
@@ -25,11 +28,18 @@ import { parseClaudeHookPayload, summarizeClaudeNotification, summarizeClaudeSto
 import { requestJson } from "./http-client.js";
 import { runTmuxSwitcher } from "./tmux/switcher.js";
 import { runTmuxInboxPopup } from "./tmux/inbox-popup.js";
+import { buildDebugStateReport, renderDebugStateReport } from "./debug-state.js";
 import { getDashboardCommandSpec } from "./dashboard/command-spec.js";
 import { findLiveDashboardTarget, openDashboardTarget, pruneDashboardArtifacts, resolveDashboardTarget, } from "./dashboard/targets.js";
 import { invalidateTmuxStatuslineArtifacts } from "./tmux/statusline-cache.js";
 import { loadStatusline, renderTmuxStatuslineFromData } from "./tmux/statusline.js";
 import { persistProjectRuntimeSnapshotsBeforeTmuxStop } from "./multiplexer/service-state-snapshot.js";
+import { configureLogging, log, resolveLoggingRuntimeConfig } from "./debug.js";
+import { createRuntimeTopologyStore } from "./runtime-core/topology-store.js";
+import { listTopologySessionStates } from "./runtime-core/topology-sessions.js";
+import { listTopologyWorktreeGraveyard, listTopologyWorktreeGraveyardPaths, } from "./runtime-core/topology-worktrees.js";
+import { buildRuntimeMigrationReport, importRuntimeMigration, renderRuntimeMigrationImportResult, renderRuntimeMigrationReport, renderRuntimeMigrationRollbackResult, rollbackRuntimeMigration, } from "./runtime-migration.js";
+import { DEFAULT_LOCAL_UI_HOST, DEFAULT_LOCAL_UI_PORT, openUrlInBrowser, startLocalUiServer, } from "./local-ui-server.js";
 const program = new Command();
 class ProjectServiceVersionError extends Error {
     projectRoot;
@@ -61,6 +71,7 @@ function renderProjectServiceVersionHelp(error) {
 }
 async function restartStaleControlPlane(projectRoot) {
     console.error(`aimux: restarting stale daemon-managed control plane for ${projectRoot}...`);
+    log.warn("restarting stale control plane", "runtime", { projectRoot });
     await stopDaemon();
     removeMetadataEndpoint(projectRoot);
     await ensureDaemonRunning();
@@ -94,9 +105,21 @@ async function waitForVerifiedProjectService(projectRoot, opts) {
                 const health = await fetchProjectServiceHealth(endpoint);
                 lastServiceInfo = health.serviceInfo ?? null;
                 if (manifestsMatch(expected, health.serviceInfo)) {
+                    log.info("project service verified", "runtime", {
+                        projectRoot,
+                        endpoint,
+                        pid: health.pid,
+                        elapsedMs: Date.now() - startedAt,
+                    });
                     return { endpoint, health };
                 }
                 lastError = `project service manifest mismatch: expected ${JSON.stringify(expected)} actual ${JSON.stringify(health.serviceInfo ?? null)}`;
+                log.warn("project service manifest mismatch", "runtime", {
+                    projectRoot,
+                    endpoint,
+                    expected,
+                    actual: health.serviceInfo ?? null,
+                });
             }
             catch (error) {
                 lastError = error instanceof Error ? error.message : String(error);
@@ -106,6 +129,11 @@ async function waitForVerifiedProjectService(projectRoot, opts) {
                         lastError.includes("ECONNRESET") ||
                         lastError.includes("socket hang up"))) {
                     respawnAttempted = true;
+                    log.warn("respawning project service after connection failure", "runtime", {
+                        projectRoot,
+                        endpoint,
+                        error: lastError,
+                    });
                     removeMetadataEndpoint(projectRoot);
                     await ensureProjectService(projectRoot);
                 }
@@ -118,6 +146,7 @@ async function waitForVerifiedProjectService(projectRoot, opts) {
             }
             else if (!respawnAttempted && Date.now() - missingEndpointSince >= 1000) {
                 respawnAttempted = true;
+                log.warn("respawning project service after missing endpoint", "runtime", { projectRoot });
                 await stopProjectService(projectRoot);
                 removeMetadataEndpoint(projectRoot);
                 await ensureProjectService(projectRoot);
@@ -160,7 +189,7 @@ function rewriteLocalStatuslineArtifacts(projectRoot, tmux, dashboardSessionName
     if (dashboardSessionName) {
         writeStatusFile(`bottom-dashboard-${dashboardSessionName}.txt`, dashboardBottom);
     }
-    for (const entry of data.sessions ?? []) {
+    for (const entry of [...(data.sessions ?? []), ...(data.teammates ?? [])]) {
         if (!entry.tmuxWindowId)
             continue;
         const renderOptions = {
@@ -216,34 +245,74 @@ async function postProjectServiceJsonOrLocal(path, body, fallback) {
         return fallback();
     }
 }
+async function getProjectServiceJsonOrLocal(path, fallback) {
+    try {
+        return await getProjectServiceJson(path);
+    }
+    catch {
+        return fallback();
+    }
+}
 function exitAfterOpen() {
     process.exit(0);
 }
 async function postLiveProjectServiceJsonOrLocal(projectRoot, path, body, fallback) {
+    let endpoint;
     try {
-        const endpoint = await resolveProjectServiceEndpoint(projectRoot);
-        if (!endpoint) {
-            return fallback();
-        }
-        const { status, json } = await requestJson(`http://${endpoint.host}:${endpoint.port}${path}`, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body,
-        });
-        if (status < 200 || status >= 300 || json?.ok === false) {
-            throw new Error(json?.error || `request failed: ${status}`);
-        }
-        return json;
+        endpoint = await resolveProjectServiceEndpoint(projectRoot);
     }
     catch {
         return fallback();
     }
+    if (!endpoint) {
+        return fallback();
+    }
+    const { status, json } = await requestJson(`http://${endpoint.host}:${endpoint.port}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+    });
+    if (status === 404 || status === 405 || status === 501) {
+        return fallback();
+    }
+    if (status < 200 || status >= 300 || json?.ok === false) {
+        throw new Error(json?.error || `request failed: ${status}`);
+    }
+    return json;
+}
+async function getLiveProjectServiceJsonOrLocal(projectRoot, path, fallback) {
+    let endpoint;
+    try {
+        endpoint = await resolveProjectServiceEndpoint(projectRoot);
+    }
+    catch {
+        return fallback();
+    }
+    if (!endpoint) {
+        return fallback();
+    }
+    let status;
+    let json;
+    try {
+        ({ status, json } = await requestJson(`http://${endpoint.host}:${endpoint.port}${path}`, {
+            method: "GET",
+        }));
+    }
+    catch {
+        return fallback();
+    }
+    if (status === 404 || status === 405 || status === 501) {
+        return fallback();
+    }
+    if (status < 200 || status >= 300 || json?.ok === false) {
+        throw new Error(json?.error || `request failed: ${status}`);
+    }
+    return json;
 }
 async function resolveClaudeHookSessionId(explicitSessionId, payloadSessionId) {
     if (!payloadSessionId)
         return explicitSessionId;
-    const state = Multiplexer.loadState();
-    const match = state?.sessions.find((session) => session.backendSessionId === payloadSessionId);
+    const match = listTopologySessionStates().find((session) => session.backendSessionId === payloadSessionId);
     return match?.id ?? explicitSessionId;
 }
 async function resolveProjectServiceEndpoint(projectRoot = resolveProjectRoot(process.cwd())) {
@@ -371,20 +440,101 @@ function ensureTmuxAvailable(tmux) {
         process.exit(1);
     }
 }
+function commandPath(command) {
+    const names = [];
+    let current = command;
+    while (current) {
+        const name = current.name();
+        if (name)
+            names.unshift(name);
+        current = current.parent ?? null;
+    }
+    return names;
+}
+function loggingProcessKind(command) {
+    const names = commandPath(command);
+    if (names.at(-1) === "__project-service-internal")
+        return "project-service";
+    if (names.at(-2) === "daemon" && names.at(-1) === "run")
+        return "daemon";
+    return "cli";
+}
+function configureLoggingForCommand(command) {
+    const processKind = loggingProcessKind(command);
+    const config = loadConfig();
+    const path = processKind === "daemon" ? getDaemonLogPath() : getProjectLogPath();
+    const cli = program.opts();
+    const resolved = resolveLoggingRuntimeConfig({
+        config: config.logging,
+        env: process.env,
+        cli,
+        path,
+        processKind,
+        projectId: getProjectId(),
+        projectRoot: getRepoRoot(),
+    });
+    configureLogging(resolved);
+    log.info("logging configured", "logging", {
+        path: resolved.path,
+        level: resolved.level,
+        categories: resolved.categories,
+    });
+}
+function parseLineCount(value) {
+    const parsed = Number.parseInt(value ?? "80", 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 80;
+}
+function parsePortOption(value, fallback) {
+    const parsed = Number.parseInt(value ?? String(fallback), 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65_535) {
+        throw new Error(`Port must be an integer between 1 and 65535, got ${value}`);
+    }
+    return parsed;
+}
+function selectedLogPath(opts) {
+    return opts.daemon ? getDaemonLogPath() : getProjectLogPath();
+}
+function readLastLogLines(path, lines) {
+    if (!existsSync(path))
+        return "";
+    const content = readFileSync(path, "utf-8");
+    const allLines = content.split(/\r?\n/);
+    if (allLines.at(-1) === "")
+        allLines.pop();
+    return allLines.slice(-lines).join("\n");
+}
+const pkgJsonPath = pathJoin(pathDirname(fileURLToPath(import.meta.url)), "..", "package.json");
+const pkgVersion = JSON.parse(readFileSync(pkgJsonPath, "utf8")).version;
 program
     .name("aimux")
     .description("Native CLI agent multiplexer")
-    .version("0.1.0")
+    .version(pkgVersion)
     .argument("[tool]", "Tool to run (e.g. claude, codex, aider)")
     .argument("[args...]", "Arguments to pass to the tool")
     .option("--resume", "Resume previous sessions using native tool resume")
     .option("--restore", "Start fresh sessions with injected history context")
     .option("--tmux-dashboard-internal", "Internal tmux dashboard entrypoint")
+    .option("--debug", "Enable debug logging for this process")
+    .option("--trace", "Enable trace logging for this process")
+    .option("--log-level <level>", "Enable logging at level: error|warn|info|debug|trace")
+    .option("--log-category <categories>", "Comma-separated log categories to include")
     .hook("preAction", async (_thisCommand, actionCommand) => {
+    const names = commandPath(actionCommand);
+    const isMigrationAudit = names.at(-2) === "migration" && names.at(-1) === "audit";
+    if (isMigrationAudit) {
+        return;
+    }
     const opts = typeof actionCommand?.opts === "function" ? actionCommand.opts() : {};
-    const requestedProject = typeof opts.project === "string" ? opts.project : undefined;
+    const requestedProject = typeof opts.project === "string"
+        ? opts.project
+        : typeof opts.projectRoot === "string"
+            ? opts.projectRoot
+            : typeof opts["project-root"] === "string"
+                ? opts["project-root"]
+                : undefined;
     const projectRoot = requestedProject ? resolveProjectRoot(pathResolve(requestedProject)) : undefined;
     await initPaths(projectRoot);
+    configureLoggingForCommand(actionCommand);
 })
     .action(async (tool, args, opts) => {
     const originalCwd = process.cwd();
@@ -445,11 +595,19 @@ program
     process.on("SIGTERM", shutdown);
     process.on("uncaughtException", (err) => {
         cleanupAll();
+        log.error("uncaught exception", "runtime", {
+            error: err instanceof Error ? err.message : String(err),
+            stack: err instanceof Error ? err.stack : undefined,
+        });
         console.error(err);
         process.exit(1);
     });
     process.on("unhandledRejection", (reason) => {
         cleanupAll();
+        log.error("unhandled rejection", "runtime", {
+            error: reason instanceof Error ? reason.message : String(reason),
+            stack: reason instanceof Error ? reason.stack : undefined,
+        });
         console.error(reason);
         process.exit(1);
     });
@@ -531,8 +689,11 @@ program
     try {
         if (sessionId) {
             const projectRoot = await prepareProjectContext(opts.project);
-            const mux = new Multiplexer();
-            const result = await mux.stopAgent(sessionId);
+            await ensureDaemonProjectReady(projectRoot);
+            const result = await postLiveProjectServiceJsonOrLocal(projectRoot, "/agents/stop", { sessionId }, () => {
+                const mux = new Multiplexer();
+                return mux.stopAgent(sessionId);
+            });
             if (opts.json) {
                 console.log(JSON.stringify({
                     ok: true,
@@ -555,6 +716,7 @@ program
                 projectServiceStopped: result.projectServiceStopped,
                 tmuxSessionsKilled: result.tmuxSessionsKilled,
             }, null, 2));
+            process.exitCode = 1;
             return;
         }
         console.log(`Stopped project runtime for ${projectRoot}`);
@@ -606,6 +768,47 @@ program
 const hostCmd = program
     .command("host")
     .description("Advanced compatibility wrappers for legacy daemon-managed project services");
+program
+    .command("ui")
+    .description("Run the first-party local web UI from the built app bundle")
+    .option("--host <host>", "Loopback host to bind", DEFAULT_LOCAL_UI_HOST)
+    .option("--port <port>", "Local UI port", String(DEFAULT_LOCAL_UI_PORT))
+    .option("--daemon-url <url>", "Daemon URL for the UI to call")
+    .option("--no-daemon", "Do not ensure the local daemon before serving")
+    .option("--open", "Open the UI in the default browser")
+    .action(async (opts) => {
+    try {
+        const shouldEnsureDaemon = opts.daemon !== false;
+        const daemonInfo = shouldEnsureDaemon ? await ensureDaemonRunning() : null;
+        const daemonUrl = opts.daemonUrl?.trim() || `http://${getDaemonHost()}:${daemonInfo?.port ?? getDaemonPort()}`;
+        const server = await startLocalUiServer({
+            host: opts.host,
+            port: parsePortOption(opts.port, DEFAULT_LOCAL_UI_PORT),
+            config: {
+                connectionMode: "local",
+                daemonUrl,
+            },
+        });
+        console.log(`aimux UI: ${server.url}`);
+        console.log(`Daemon: ${daemonUrl}`);
+        console.log("Press Ctrl-C to stop.");
+        if (opts.open) {
+            openUrlInBrowser(server.url);
+        }
+        const shutdown = async () => {
+            await server.close();
+            process.exit(0);
+        };
+        process.on("SIGINT", () => void shutdown());
+        process.on("SIGTERM", () => void shutdown());
+        await new Promise(() => { });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+});
 program
     .command("serve")
     .description("Advanced: ensure the legacy daemon-backed project control service is running")
@@ -718,27 +921,22 @@ hostCmd
     console.log(`Restarted project service for ${dashboardSession.sessionName}`);
 });
 hostCmd
-    .command("agent-send")
-    .description("Send raw input to a running agent session over the project HTTP service")
-    .argument("<sessionId>", "Agent session ID")
-    .argument("[data...]", "Input to send")
-    .option("--stdin", "Read the full input payload from stdin")
-    .option("--submit", "Submit after writing the input")
-    .action(async (sessionId, data, opts) => {
+    .command("topology")
+    .description("Show the runtime topology YAML path or parsed contents")
+    .option("--json", "Emit parsed topology JSON")
+    .option("--raw", "Print raw YAML contents")
+    .action(async (opts) => {
     await initPaths();
-    const payload = opts.stdin === true ? await readAllStdin() : data.join(" ");
-    if (!payload) {
-        throw new Error("input data is required");
-    }
-    const result = await postProjectServiceJson("/agents/input", {
-        sessionId,
-        data: payload,
-        submit: opts.submit === true,
-    });
-    if (result.accepted === false) {
-        throw new Error(result.error || `agent input failed for ${result.sessionId}`);
+    const path = getRuntimeTopologyPath();
+    if (opts.json) {
+        console.log(JSON.stringify(createRuntimeTopologyStore(path).read(), null, 2));
+        return;
     }
-    console.log(`sent input to ${result.sessionId}`);
+    if (opts.raw) {
+        console.log(readFileSync(path, "utf-8"));
+        return;
+    }
+    console.log(path);
 });
 hostCmd
     .command("agent-read")
@@ -928,9 +1126,20 @@ daemonCmd
     .action(async (opts) => {
     const info = loadDaemonInfo();
     const state = loadDaemonState();
+    let relay = { status: "off" };
+    if (info) {
+        try {
+            const result = await requestDaemonJson("/relay/status");
+            relay = result.relay;
+        }
+        catch {
+            // Relay status unavailable — leave as off.
+        }
+    }
     const payload = {
         daemon: info,
         projects: Object.values(state.projects),
+        relay,
     };
     if (opts.json) {
         console.log(JSON.stringify(payload, null, 2));
@@ -942,6 +1151,13 @@ daemonCmd
     }
     console.log(`Daemon pid=${info.pid} port=${info.port}`);
     console.log(`Managed projects: ${Object.keys(state.projects).length}`);
+    const r = relay;
+    if (r.status && r.status !== "off") {
+        console.log(`Relay: ${r.status}${r.relayUrl ? ` (${r.relayUrl})` : ""}`);
+    }
+    else {
+        console.log("Relay: off");
+    }
 });
 daemonCmd
     .command("projects")
@@ -1001,11 +1217,19 @@ program
     process.on("SIGTERM", shutdown);
     process.on("uncaughtException", (err) => {
         cleanupAll();
+        log.error("project service uncaught exception", "runtime", {
+            error: err instanceof Error ? err.message : String(err),
+            stack: err instanceof Error ? err.stack : undefined,
+        });
         console.error(err);
         process.exit(1);
     });
     process.on("unhandledRejection", (reason) => {
         cleanupAll();
+        log.error("project service unhandled rejection", "runtime", {
+            error: reason instanceof Error ? reason.message : String(reason),
+            stack: reason instanceof Error ? reason.stack : undefined,
+        });
         console.error(reason);
         process.exit(1);
     });
@@ -1039,15 +1263,8 @@ projectsCmd
         return;
     }
     for (const project of projects) {
-        const liveBadge = project.sessions.some((session) => session.status !== "offline") ? "live" : "idle";
+        const liveBadge = project.serviceAlive ? "live" : "idle";
         console.log(`${project.name}  ${liveBadge}  ${project.path}`);
-        if (project.sessions.length === 0)
-            continue;
-        for (const session of project.sessions) {
-            const label = session.label ? ` ${session.label}` : "";
-            const headline = session.headline ? ` - ${session.headline}` : "";
-            console.log(`  ${session.id}  ${session.tool}  ${session.status}${label}${headline}`);
-        }
     }
 });
 program
@@ -1073,6 +1290,166 @@ program
     llmCompact(sessionIds);
     console.log(`Done. Summary written to ${getContextDir()}/summary.md`);
 });
+program
+    .command("login")
+    .description("Sign in to enable remote access via aimux.app")
+    .option("--web-app-url <url>", "Override the web app URL")
+    // No --relay-url here: the token is minted by whichever relay the web app
+    // points at, so a CLI override would just store a relay URL that rejects
+    // the resulting token (different RELAY_TOKEN_SECRET).
+    .action(async (opts) => {
+    try {
+        const { userId } = await runLoginFlow({ webAppUrl: opts.webAppUrl });
+        let relayStatus = null;
+        let relayError = null;
+        if (loadDaemonInfo()) {
+            try {
+                const result = await requestDaemonJson("/relay/enable", { method: "POST" });
+                const relay = result.relay;
+                relayStatus = relay.status ?? "unknown";
+                relayError = relay.lastError ?? null;
+            }
+            catch (err) {
+                relayError = err instanceof Error ? err.message : String(err);
+            }
+        }
+        console.log(`\n✓ Logged in as ${userId}`);
+        if (relayStatus) {
+            console.log(`Remote access is enabled (connection: ${relayStatus}).`);
+            if (relayError)
+                console.log(`Last error: ${relayError}`);
+        }
+        else {
+            console.log("Remote access is enabled. The daemon will connect on next start.");
+            if (relayError)
+                console.log(`Daemon refresh failed: ${relayError}`);
+        }
+    }
+    catch (err) {
+        console.error(`Login failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
+program
+    .command("logout")
+    .description("Clear stored credentials and disable remote access")
+    .action(async () => {
+    // If the daemon is running it already has the credential loaded into
+    // memory; tell it to disconnect before we yank the file so the running
+    // process stops talking to the relay immediately (best-effort — we
+    // ignore failures since the daemon may not be up).
+    if (loadDaemonInfo()) {
+        try {
+            await requestDaemonJson("/relay/disable", { method: "POST" });
+        }
+        catch {
+            // daemon offline or refused; the file removal below still kills
+            // future startup, so this isn't fatal.
+        }
+    }
+    const result = clearCredentials();
+    if (result === "cleared")
+        console.log("✓ Logged out. Remote access disabled.");
+    else if (result === "none")
+        console.log("Not logged in.");
+    else {
+        console.error("Failed to remove credentials file — check permissions.");
+        process.exitCode = 1;
+    }
+});
+program
+    .command("whoami")
+    .description("Show the current remote-access login status")
+    .option("--json", "Emit JSON")
+    .action((opts) => {
+    const creds = loadCredentials();
+    if (opts.json) {
+        console.log(JSON.stringify(creds
+            ? { loggedIn: true, userId: creds.userId, relayUrl: creds.relayUrl, remoteEnabled: creds.remoteEnabled }
+            : { loggedIn: false }, null, 2));
+        return;
+    }
+    if (!creds) {
+        console.log("Not logged in. Run `aimux login` to enable remote access.");
+        return;
+    }
+    console.log(`Logged in as ${creds.userId}`);
+    console.log(`Relay: ${creds.relayUrl}`);
+    console.log(`Remote access: ${creds.remoteEnabled ? "enabled" : "disabled"}`);
+});
+const remoteCmd = program.command("remote").description("Manage remote access via the relay");
+const securityCmd = program.command("security").description("Manage aimux security controls");
+remoteCmd
+    .command("status")
+    .description("Show relay connection status")
+    .option("--json", "Emit JSON")
+    .action(async (opts) => {
+    const creds = loadCredentials();
+    let relay = { status: "off" };
+    if (loadDaemonInfo()) {
+        try {
+            const result = await requestDaemonJson("/relay/status");
+            relay = result.relay;
+        }
+        catch {
+            // Daemon is not reachable — fall back to credential state.
+        }
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ loggedIn: Boolean(creds), relay }, null, 2));
+        return;
+    }
+    if (!creds) {
+        console.log("Not logged in. Run `aimux login` to enable remote access.");
+        return;
+    }
+    const r = relay;
+    console.log(`Remote access: ${creds.remoteEnabled ? "enabled" : "disabled"}`);
+    console.log(`Relay: ${creds.relayUrl}`);
+    console.log(`Connection: ${r.status ?? "unknown"}`);
+    if (r.lastError)
+        console.log(`Last error: ${r.lastError}`);
+});
+remoteCmd
+    .command("enable")
+    .description("Enable remote access and connect to the relay")
+    .action(async () => {
+    if (!loadCredentials()) {
+        console.error("Not logged in. Run `aimux login` first.");
+        process.exit(1);
+    }
+    await ensureDaemonRunning();
+    const result = await requestDaemonJson("/relay/enable", { method: "POST" });
+    const r = result.relay;
+    console.log(`✓ Remote access enabled (connection: ${r.status ?? "unknown"})`);
+});
+remoteCmd
+    .command("disable")
+    .description("Disable remote access and disconnect from the relay")
+    .action(async () => {
+    if (loadDaemonInfo()) {
+        await requestDaemonJson("/relay/disable", { method: "POST" });
+        console.log("✓ Remote access disabled. Daemon disconnected from relay.");
+        return;
+    }
+    setRemoteEnabled(false);
+    console.log("✓ Remote access disabled.");
+});
+securityCmd
+    .command("unlock")
+    .description("Clear relay security lockdown after re-authenticating")
+    .option("--web-app-url <url>", "Override the web app URL")
+    .action(async (opts) => {
+    try {
+        const { userId } = await runLoginFlow({ webAppUrl: opts.webAppUrl, action: "security-unlock" });
+        console.log(`\n✓ Security unlocked for ${userId}`);
+        console.log("Remote access is enabled with a fresh daemon token. Restart the daemon to reconnect immediately.");
+    }
+    catch (err) {
+        console.error(`Security unlock failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
 async function prepareProjectContext(requestedProject) {
     const requestedPath = pathResolve(requestedProject ?? process.cwd());
     const projectRoot = resolveProjectRoot(requestedPath);
@@ -1080,9 +1457,13 @@ async function prepareProjectContext(requestedProject) {
     process.chdir(projectRoot);
     return projectRoot;
 }
-function printWorktrees(projectRoot) {
+function listVisibleLocalWorktrees(projectRoot) {
+    const graveyardPaths = listTopologyWorktreeGraveyardPaths();
+    return listWorktrees(projectRoot).filter((worktree) => !graveyardPaths.has(worktree.path));
+}
+function printWorktrees(projectRoot, worktreesInput) {
     try {
-        const worktrees = listWorktrees(projectRoot);
+        const worktrees = worktreesInput ?? listWorktrees(projectRoot);
         if (worktrees.length === 0) {
             console.log("No worktrees found.");
             return;
@@ -1099,9 +1480,55 @@ function printWorktrees(projectRoot) {
         process.exit(1);
     }
 }
+function printGraveyard(input) {
+    const entries = Array.isArray(input.entries) ? input.entries : [];
+    const worktrees = Array.isArray(input.worktrees) ? input.worktrees : [];
+    if (entries.length === 0 && worktrees.length === 0) {
+        console.log("Graveyard is empty.");
+        return;
+    }
+    if (worktrees.length > 0) {
+        console.log("Worktrees");
+        console.log("Name".padEnd(30) + "Branch".padEnd(35) + "Path");
+        console.log("-".repeat(95));
+        for (const worktree of worktrees) {
+            console.log(String(worktree.name ?? "?").padEnd(30) +
+                String(worktree.branch ?? "").padEnd(35) +
+                String(worktree.path ?? "?"));
+        }
+    }
+    if (entries.length > 0) {
+        if (worktrees.length > 0)
+            console.log("");
+        console.log("Agents");
+        console.log("ID".padEnd(25) + "Tool".padEnd(15) + "Backend Session ID");
+        console.log("-".repeat(70));
+        for (const session of entries) {
+            console.log(String(session.id ?? "?").padEnd(25) +
+                String(session.command ?? session.tool ?? "?").padEnd(15) +
+                String(session.backendSessionId ?? "(none)"));
+        }
+    }
+}
 const worktreeCmd = program.command("worktree").description("Manage git worktrees");
-worktreeCmd.action(() => {
-    printWorktrees();
+async function ensureDaemonProjectReadyForFallback(projectRoot) {
+    try {
+        await ensureDaemonProjectReady(projectRoot);
+    }
+    catch (err) {
+        if (err instanceof ProjectServiceVersionError) {
+            throw err;
+        }
+    }
+}
+worktreeCmd.action(async () => {
+    const projectRoot = await prepareProjectContext();
+    await ensureDaemonProjectReadyForFallback(projectRoot);
+    const result = await getLiveProjectServiceJsonOrLocal(projectRoot, "/worktrees", () => ({
+        ok: true,
+        worktrees: listVisibleLocalWorktrees(projectRoot),
+    }));
+    printWorktrees(projectRoot, result.worktrees ?? []);
 });
 const threadCmd = program.command("thread").description("Inspect and manage orchestration threads");
 program
@@ -1109,8 +1536,9 @@ program
     .description("Alias for thread list")
     .option("--session <sessionId>", "Filter to threads involving a session")
     .option("--json", "Emit JSON")
-    .action((opts) => {
-    const summaries = listThreadSummaries(opts.session);
+    .action(async (opts) => {
+    const query = opts.session ? `?session=${encodeURIComponent(opts.session)}` : "";
+    const summaries = await getProjectServiceJsonOrLocal(`/threads${query}`, () => listThreadSummaries(opts.session));
     if (opts.json) {
         console.log(JSON.stringify(summaries, null, 2));
         return;
@@ -1134,8 +1562,9 @@ threadCmd
     .description("List orchestration threads")
     .option("--session <sessionId>", "Filter to threads involving a session")
     .option("--json", "Emit JSON")
-    .action((opts) => {
-    const summaries = listThreadSummaries(opts.session);
+    .action(async (opts) => {
+    const query = opts.session ? `?session=${encodeURIComponent(opts.session)}` : "";
+    const summaries = await getProjectServiceJsonOrLocal(`/threads${query}`, () => listThreadSummaries(opts.session));
     if (opts.json) {
         console.log(JSON.stringify(summaries, null, 2));
         return;
@@ -1159,13 +1588,18 @@ threadCmd
     .description("Show a thread and its messages")
     .argument("<threadId>")
     .option("--json", "Emit JSON")
-    .action((threadId, opts) => {
-    const thread = readThread(threadId);
-    if (!thread) {
+    .action(async (threadId, opts) => {
+    const detail = await getProjectServiceJsonOrLocal(`/threads/${encodeURIComponent(threadId)}`, () => {
+        const thread = readThread(threadId);
+        if (!thread)
+            return null;
+        return { thread, messages: readMessages(threadId) };
+    });
+    if (!detail?.thread) {
         console.error(`aimux: thread not found: ${threadId}`);
         process.exit(1);
     }
-    const messages = readMessages(threadId);
+    const { thread, messages } = detail;
     if (opts.json) {
         console.log(JSON.stringify({ thread, messages }, null, 2));
         return;
@@ -1191,18 +1625,25 @@ threadCmd
     .requiredOption("--from <sessionId>", "Creating session")
     .requiredOption("--participants <ids>", "Comma-separated participant session ids")
     .option("--kind <kind>", "conversation|task|review|handoff|user", "conversation")
-    .action((opts) => {
+    .action(async (opts) => {
     const participants = opts.participants
         .split(",")
         .map((value) => value.trim())
         .filter(Boolean);
-    const thread = createThread({
+    const result = await postProjectServiceJsonOrLocal("/threads/open", {
         title: opts.title,
+        from: opts.from,
+        participants,
         kind: opts.kind ?? "conversation",
-        createdBy: opts.from,
-        participants: [...new Set([opts.from, ...participants])],
-    });
-    console.log(thread.id);
+    }, () => ({
+        thread: createThread({
+            title: opts.title,
+            kind: opts.kind ?? "conversation",
+            createdBy: opts.from,
+            participants: [...new Set([opts.from, ...participants])],
+        }),
+    }));
+    console.log(result.thread.id);
 });
 threadCmd
     .command("send")
@@ -1212,36 +1653,46 @@ threadCmd
     .requiredOption("--from <sessionId>", "Sending session")
     .option("--to <ids>", "Comma-separated recipient session ids")
     .option("--kind <kind>", "request|reply|status|decision|handoff|note", "note")
-    .action((threadId, body, opts) => {
-    const thread = readThread(threadId);
-    if (!thread) {
-        console.error(`aimux: thread not found: ${threadId}`);
-        process.exit(1);
-    }
+    .action(async (threadId, body, opts) => {
     const to = opts.to
         ?.split(",")
         .map((value) => value.trim())
         .filter(Boolean);
-    const message = sendThreadMessage({
+    const result = await postProjectServiceJsonOrLocal("/threads/send", {
         threadId,
         from: opts.from,
         to,
         kind: opts.kind ?? "note",
         body,
-    }).message;
-    console.log(message.id);
+    }, () => {
+        if (!readThread(threadId)) {
+            console.error(`aimux: thread not found: ${threadId}`);
+            process.exit(1);
+        }
+        return sendThreadMessage({
+            threadId,
+            from: opts.from,
+            to,
+            kind: opts.kind ?? "note",
+            body,
+        });
+    });
+    console.log(result.message.id);
 });
 threadCmd
     .command("mark-seen")
     .description("Mark a thread as seen for a participant")
     .argument("<threadId>")
     .requiredOption("--session <sessionId>", "Participant session id")
-    .action((threadId, opts) => {
-    const thread = markThreadSeen(threadId, opts.session);
-    if (!thread) {
-        console.error(`aimux: thread not found: ${threadId}`);
-        process.exit(1);
-    }
+    .action(async (threadId, opts) => {
+    await postProjectServiceJsonOrLocal("/threads/mark-seen", { threadId, session: opts.session }, () => {
+        const thread = markThreadSeen(threadId, opts.session);
+        if (!thread) {
+            console.error(`aimux: thread not found: ${threadId}`);
+            process.exit(1);
+        }
+        return { ok: true, thread };
+    });
     console.log("ok");
 });
 threadCmd
@@ -1381,7 +1832,11 @@ handoffCmd
     catch {
         const result = sendHandoff({
             from: opts.from ?? "user",
-            to: to ?? [],
+            to: to?.length
+                ? to
+                : [opts.assignee, opts.tool]
+                    .map((value) => value?.trim())
+                    .filter((value) => Boolean(value)),
             body,
             title: opts.title,
             worktreePath: opts.worktree,
@@ -1451,10 +1906,20 @@ taskCmd
     .option("--session <sessionId>", "Filter to tasks assigned to or created by a session")
     .option("--status <status>", "Filter by task status")
     .option("--json", "Emit JSON")
-    .action((opts) => {
-    const tasks = readAllTasks()
-        .filter((task) => !opts.session || task.assignedTo === opts.session || task.assignedBy === opts.session)
-        .filter((task) => !opts.status || task.status === opts.status);
+    .action(async (opts) => {
+    const params = new URLSearchParams();
+    if (opts.session)
+        params.set("session", opts.session);
+    if (opts.status)
+        params.set("status", opts.status);
+    const query = params.toString();
+    const result = await getProjectServiceJsonOrLocal(`/tasks${query ? `?${query}` : ""}`, () => ({
+        ok: true,
+        tasks: readAllTasks()
+            .filter((task) => !opts.session || task.assignedTo === opts.session || task.assignedBy === opts.session)
+            .filter((task) => !opts.status || task.status === opts.status),
+    }));
+    const tasks = Array.isArray(result.tasks) ? result.tasks : [];
     if (opts.json) {
         console.log(JSON.stringify({ tasks }, null, 2));
         return;
@@ -1475,14 +1940,23 @@ taskCmd
     .description("Show an orchestrated task")
     .argument("<taskId>")
     .option("--json", "Emit JSON")
-    .action((taskId, opts) => {
-    const task = readTask(taskId);
-    if (!task) {
+    .action(async (taskId, opts) => {
+    const detail = await getProjectServiceJsonOrLocal(`/tasks/${encodeURIComponent(taskId)}`, () => {
+        const task = readTask(taskId);
+        if (!task)
+            return null;
+        return {
+            ok: true,
+            task,
+            thread: task.threadId ? readThread(task.threadId) : undefined,
+            messages: task.threadId ? readMessages(task.threadId) : [],
+        };
+    });
+    if (!detail?.task) {
         console.error(`aimux: task not found: ${taskId}`);
         process.exit(1);
     }
-    const thread = task.threadId ? readThread(task.threadId) : undefined;
-    const messages = task.threadId ? readMessages(task.threadId) : [];
+    const { task, thread, messages } = detail;
     if (opts.json) {
         console.log(JSON.stringify({ task, thread, messages }, null, 2));
         return;
@@ -1743,12 +2217,17 @@ worktreeCmd
     .option("--json", "Emit JSON")
     .action(async (opts) => {
     const projectRoot = await prepareProjectContext(opts.project);
-    const worktrees = listWorktrees(projectRoot);
+    await ensureDaemonProjectReadyForFallback(projectRoot);
+    const result = await getLiveProjectServiceJsonOrLocal(projectRoot, "/worktrees", () => ({
+        ok: true,
+        worktrees: listVisibleLocalWorktrees(projectRoot),
+    }));
+    const worktrees = result.worktrees ?? [];
     if (opts.json) {
         console.log(JSON.stringify(worktrees, null, 2));
         return;
     }
-    printWorktrees(projectRoot);
+    printWorktrees(projectRoot, worktrees);
 });
 worktreeCmd
     .command("create <name>")
@@ -1758,7 +2237,12 @@ worktreeCmd
     .action(async (name, opts) => {
     try {
         const projectRoot = await prepareProjectContext(opts.project);
-        const createdPath = createWorktree(name, projectRoot);
+        await ensureDaemonProjectReadyForFallback(projectRoot);
+        const result = await postLiveProjectServiceJsonOrLocal(projectRoot, "/worktrees/create", { name }, () => {
+            const mux = new Multiplexer();
+            return mux.createDesktopWorktree(name);
+        });
+        const createdPath = result.path;
         if (opts.json) {
             console.log(JSON.stringify({
                 ok: true,
@@ -1776,6 +2260,114 @@ worktreeCmd
         process.exit(1);
     }
 });
+worktreeCmd
+    .command("remove <path>")
+    .description("Remove a git worktree")
+    .option("--project <path>", "Project path")
+    .option("--json", "Emit JSON")
+    .action(async (targetPath, opts) => {
+    try {
+        const inputCwd = process.cwd();
+        const resolvedPath = pathResolve(inputCwd, targetPath);
+        const projectRoot = await prepareProjectContext(opts.project);
+        await ensureDaemonProjectReadyForFallback(projectRoot);
+        const result = await postLiveProjectServiceJsonOrLocal(projectRoot, "/worktrees/remove", { path: resolvedPath }, () => {
+            const mux = new Multiplexer();
+            return mux.removeDesktopWorktree(resolvedPath);
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, projectRoot, path: result.path, status: result.status }, null, 2));
+            return;
+        }
+        console.log(`${result.status === "removing" ? "removing" : "removed"} ${result.path}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+});
+worktreeCmd
+    .command("graveyard <path>")
+    .description("Move a worktree to the graveyard without deleting the checkout")
+    .option("--project <path>", "Project path")
+    .option("--json", "Emit JSON")
+    .action(async (targetPath, opts) => {
+    try {
+        const inputCwd = process.cwd();
+        const resolvedPath = pathResolve(inputCwd, targetPath);
+        const projectRoot = await prepareProjectContext(opts.project);
+        await ensureDaemonProjectReadyForFallback(projectRoot);
+        const result = await postLiveProjectServiceJsonOrLocal(projectRoot, "/worktrees/graveyard", { path: resolvedPath }, () => {
+            const mux = new Multiplexer();
+            return mux.graveyardDesktopWorktree(resolvedPath);
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, projectRoot, path: result.path, status: result.status }, null, 2));
+            return;
+        }
+        console.log(`graveyarded ${result.path}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+});
+worktreeCmd
+    .command("resurrect <path>")
+    .description("Restore a graveyarded worktree to the active worktree list")
+    .option("--project <path>", "Project path")
+    .option("--json", "Emit JSON")
+    .action(async (targetPath, opts) => {
+    try {
+        const inputCwd = process.cwd();
+        const resolvedPath = pathResolve(inputCwd, targetPath);
+        const projectRoot = await prepareProjectContext(opts.project);
+        await ensureDaemonProjectReadyForFallback(projectRoot);
+        const result = await postLiveProjectServiceJsonOrLocal(projectRoot, "/graveyard/worktrees/resurrect", { path: resolvedPath }, () => {
+            const mux = new Multiplexer();
+            return mux.resurrectGraveyardWorktree(resolvedPath);
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, projectRoot, path: result.path, status: result.status }, null, 2));
+            return;
+        }
+        console.log(`resurrected ${result.path}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+});
+worktreeCmd
+    .command("delete-graveyard <path>")
+    .description("Permanently delete a graveyarded worktree entry")
+    .option("--project <path>", "Project path")
+    .option("--json", "Emit JSON")
+    .action(async (targetPath, opts) => {
+    try {
+        const inputCwd = process.cwd();
+        const resolvedPath = pathResolve(inputCwd, targetPath);
+        const projectRoot = await prepareProjectContext(opts.project);
+        await ensureDaemonProjectReadyForFallback(projectRoot);
+        const result = await postLiveProjectServiceJsonOrLocal(projectRoot, "/graveyard/worktrees/delete", { path: resolvedPath }, () => {
+            const mux = new Multiplexer();
+            return mux.deleteGraveyardWorktree(resolvedPath);
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, projectRoot, path: result.path, status: result.status }, null, 2));
+            return;
+        }
+        console.log(`deleted ${result.path}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+});
 program
     .command("spawn")
     .description("Spawn a fresh agent session using the same flow as the dashboard")
@@ -1868,27 +2460,26 @@ graveyardCmd
     .option("--project <path>", "Project path")
     .option("--json", "Emit JSON")
     .action(async (opts) => {
-    await prepareProjectContext(opts.project);
-    const graveyardPath = getGraveyardPath();
+    const projectRoot = await prepareProjectContext(opts.project);
+    await ensureDaemonProjectReadyForFallback(projectRoot);
     try {
-        const graveyard = JSON.parse(readFileSync(graveyardPath, "utf-8"));
+        const graveyard = await getLiveProjectServiceJsonOrLocal(projectRoot, "/graveyard", () => ({
+            ok: true,
+            entries: listTopologySessionStates({ statuses: ["graveyard"] }),
+            worktrees: listTopologyWorktreeGraveyard(),
+        }));
         if (opts.json) {
-            console.log(JSON.stringify(Array.isArray(graveyard) ? graveyard : [], null, 2));
-            return;
-        }
-        if (!Array.isArray(graveyard) || graveyard.length === 0) {
-            console.log("Graveyard is empty.");
+            console.log(JSON.stringify({
+                entries: Array.isArray(graveyard.entries) ? graveyard.entries : [],
+                worktrees: Array.isArray(graveyard.worktrees) ? graveyard.worktrees : [],
+            }, null, 2));
             return;
         }
-        console.log("ID".padEnd(25) + "Tool".padEnd(15) + "Backend Session ID");
-        console.log("-".repeat(70));
-        for (const s of graveyard) {
-            console.log((s.id ?? "?").padEnd(25) + (s.command ?? s.tool ?? "?").padEnd(15) + (s.backendSessionId ?? "(none)"));
-        }
+        printGraveyard(graveyard);
     }
     catch {
         if (opts.json) {
-            console.log("[]");
+            console.log(JSON.stringify({ entries: [], worktrees: [] }, null, 2));
             return;
         }
         console.log("Graveyard is empty.");
@@ -1902,8 +2493,11 @@ graveyardCmd
     .action(async (id, opts) => {
     try {
         const projectRoot = await prepareProjectContext(opts.project);
-        const mux = new Multiplexer();
-        const result = await mux.sendAgentToGraveyard(id);
+        await ensureDaemonProjectReady(projectRoot);
+        const result = await postLiveProjectServiceJsonOrLocal(projectRoot, "/agents/kill", { sessionId: id }, () => {
+            const mux = new Multiplexer();
+            return mux.sendAgentToGraveyard(id);
+        });
         if (opts.json) {
             console.log(JSON.stringify({
                 ok: true,
@@ -1928,44 +2522,23 @@ graveyardCmd
     .option("--project <path>", "Project path")
     .option("--json", "Emit JSON")
     .action(async (id, opts) => {
-    await prepareProjectContext(opts.project);
-    const graveyardPath = getGraveyardPath();
-    if (!existsSync(graveyardPath)) {
-        console.error("Graveyard is empty.");
-        process.exit(1);
-    }
     try {
-        const graveyard = JSON.parse(readFileSync(graveyardPath, "utf-8"));
-        const idx = graveyard.findIndex((s) => s.id === id);
-        if (idx === -1) {
-            console.error(`Agent "${id}" not found in graveyard.`);
-            process.exit(1);
-        }
-        const restored = graveyard.splice(idx, 1)[0];
-        writeFileSync(graveyardPath, JSON.stringify(graveyard, null, 2) + "\n");
-        const statePath = getStatePath();
-        let state = {
-            savedAt: new Date().toISOString(),
-            cwd: process.cwd(),
-            sessions: [],
-        };
-        if (existsSync(statePath)) {
-            try {
-                state = JSON.parse(readFileSync(statePath, "utf-8"));
-            }
-            catch { }
-        }
-        state.sessions.push(restored);
-        writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
+        const projectRoot = await prepareProjectContext(opts.project);
+        await ensureDaemonProjectReady(projectRoot);
+        const result = await postLiveProjectServiceJsonOrLocal(projectRoot, "/graveyard/resurrect", { sessionId: id }, () => {
+            const mux = new Multiplexer();
+            return mux.resurrectGraveyardSession(id);
+        });
         if (opts.json) {
             console.log(JSON.stringify({
                 ok: true,
-                sessionId: id,
-                status: "offline",
+                projectRoot,
+                sessionId: result.sessionId,
+                status: result.status,
             }, null, 2));
             return;
         }
-        console.log(`Resurrected "${id}". It will appear as offline next time you start aimux.`);
+        console.log(`resurrected ${result.sessionId}`);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -2060,8 +2633,11 @@ program
     .action(async (sessionId, opts) => {
     try {
         const projectRoot = await prepareProjectContext(opts.project);
-        const mux = new Multiplexer();
-        const result = await mux.sendAgentToGraveyard(sessionId);
+        await ensureDaemonProjectReady(projectRoot);
+        const result = await postLiveProjectServiceJsonOrLocal(projectRoot, "/agents/kill", { sessionId }, () => {
+            const mux = new Multiplexer();
+            return mux.sendAgentToGraveyard(sessionId);
+        });
         if (opts.json) {
             console.log(JSON.stringify({
                 ok: true,
@@ -2113,6 +2689,75 @@ program
 const statuslineCmd = program.command("statusline").description("Manage Claude Code statusline integration");
 const doctorCmd = program.command("doctor").description("Inspect aimux runtime state");
 const repairCmd = program.command("repair").description("Repair the current project runtime in place");
+program
+    .command("debug-state <target>")
+    .description("Read-only debug snapshot for one session, service, backend session, or worktree")
+    .action((target) => {
+    const report = buildDebugStateReport({ cwd: process.cwd(), target });
+    console.log(renderDebugStateReport(report));
+});
+const migrationCmd = program
+    .command("migration")
+    .description("Explicit runtime-core migration audit, import, and rollback tooling");
+migrationCmd
+    .command("audit")
+    .description("Inspect legacy runtime artifacts without mutating project state")
+    .option("--project <path>", "Project path", process.cwd())
+    .action((opts) => {
+    const projectRoot = resolveProjectRoot(pathResolve(opts.project));
+    console.log(renderRuntimeMigrationReport(buildRuntimeMigrationReport({ cwd: projectRoot })));
+});
+migrationCmd
+    .command("import")
+    .description("Import legacy exchange artifacts into runtime-exchange.yaml with a rollback manifest")
+    .option("--project <path>", "Project path", process.cwd())
+    .action(async (opts) => {
+    const projectRoot = resolveProjectRoot(pathResolve(opts.project));
+    await initPaths(projectRoot);
+    console.log(renderRuntimeMigrationImportResult(importRuntimeMigration({ cwd: projectRoot })));
+});
+migrationCmd
+    .command("rollback <manifest>")
+    .description("Restore files recorded by a runtime migration manifest")
+    .action((manifest) => {
+    console.log(renderRuntimeMigrationRollbackResult(rollbackRuntimeMigration(pathResolve(manifest))));
+});
+const logsCmd = program.command("logs").description("Inspect persistent aimux logs");
+logsCmd
+    .command("path")
+    .description("Print the active log file path")
+    .option("--daemon", "Show the global daemon log path")
+    .option("--project <path>", "Project path")
+    .action((opts) => {
+    console.log(selectedLogPath(opts));
+});
+logsCmd
+    .command("tail")
+    .description("Print recent log lines")
+    .option("--daemon", "Tail the global daemon log")
+    .option("--project <path>", "Project path")
+    .option("-n, --lines <number>", "Number of lines to print", "80")
+    .action((opts) => {
+    const path = selectedLogPath(opts);
+    const output = readLastLogLines(path, parseLineCount(opts.lines));
+    if (output) {
+        console.log(output);
+        return;
+    }
+    console.error(`No log entries at ${path}`);
+    process.exit(1);
+});
+logsCmd
+    .command("clear")
+    .description("Clear the active log file")
+    .option("--daemon", "Clear the global daemon log")
+    .option("--project <path>", "Project path")
+    .action((opts) => {
+    const path = selectedLogPath(opts);
+    mkdirSync(pathDirname(path), { recursive: true });
+    writeFileSync(path, "");
+    console.log(`Cleared ${path}`);
+});
 doctorCmd
     .command("tmux")
     .description("Inspect managed tmux runtime state")
@@ -2232,20 +2877,29 @@ program
         force: true,
     }, () => {
         const kind = (opts.kind?.trim() || "notification");
-        const notification = upsertNotification({
+        const sessionId = opts.session?.trim() || undefined;
+        const context = sessionId ? metadataDisplayContext(loadMetadataState().sessions[sessionId]) : undefined;
+        const alert = contextualizeAlertInput({
+            kind,
+            sessionId,
             title,
+            message: [opts.subtitle?.trim(), body].filter(Boolean).join(" — "),
+            forceNotify: true,
+        }, context);
+        const notification = upsertNotification({
+            title: alert.title,
             subtitle: opts.subtitle?.trim() || undefined,
             body,
-            sessionId: opts.session?.trim() || undefined,
+            sessionId,
             kind,
         });
         notifyAlert({
             type: "alert",
             kind,
             projectId: getProjectId(),
-            sessionId: opts.session?.trim() || undefined,
-            title,
-            message: [opts.subtitle?.trim(), body].filter(Boolean).join(" — "),
+            sessionId,
+            title: alert.title,
+            message: alert.message,
             ts: notification.createdAt,
             forceNotify: true,
         });
@@ -2271,6 +2925,9 @@ program
     const payload = parseClaudeHookPayload(rawInput);
     const sessionId = await resolveClaudeHookSessionId(opts.session, payload.session_id);
     const result = { ok: true, action, sessionId };
+    if (payload.session_id) {
+        result.backendSessionId = payload.session_id;
+    }
     const setActivity = async (activity) => postLiveProjectServiceJsonOrLocal(projectRoot, "/set-activity", { session: sessionId, activity }, () => metadataTracker.setActivity(sessionId, activity, projectRoot));
     const setAttention = async (attention) => postLiveProjectServiceJsonOrLocal(projectRoot, "/set-attention", { session: sessionId, attention }, () => metadataTracker.setAttention(sessionId, attention, projectRoot));
     const emitEvent = async (kind, message, tone) => postLiveProjectServiceJsonOrLocal(projectRoot, "/event", { session: sessionId, event: { kind, message, tone } }, () => metadataTracker.emit(sessionId, { kind, message, tone }, projectRoot));
@@ -2278,6 +2935,21 @@ program
         ok: true,
         cleared: clearNotifications({ sessionId }),
     }));
+    const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path.trim() : "";
+    if (transcriptPath) {
+        const context = { transcriptPath };
+        await postLiveProjectServiceJsonOrLocal(projectRoot, "/set-context", { session: sessionId, context }, () => {
+            updateSessionMetadata(sessionId, (current) => ({
+                ...current,
+                context: {
+                    ...(current.context ?? {}),
+                    ...context,
+                },
+            }), projectRoot);
+            return { ok: true };
+        });
+        result.transcriptPath = transcriptPath;
+    }
     switch (action) {
         case "session-start":
         case "active":