aimux-cli 0.1.19 → 0.1.20

package/dist/connection-targets.js

@@ -1,6 +1,10 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
 const PROD_WEB_APP_URL = "https://aimux.app";
 const PROD_RELAY_URL = "wss://relay.aimux.app";
 const DEV_WEB_APP_URL = "http://localhost:8081";
+const DEV_HOME = join(homedir(), ".aimux-dev");
+const DEV_DAEMON_PORT = "43191";
 function cleanUrl(value) {
     return value.replace(/\/$/, "");
 }
@@ -8,8 +12,23 @@ function optionalEnv(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : undefined;
 }
+function normalizeHome(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed === "~")
+        return homedir();
+    if (trimmed.startsWith("~/"))
+        return resolve(homedir(), trimmed.slice(2));
+    return resolve(trimmed);
+}
+// Mirrors launcher-env's lane detection: any one dev-lane signal marks the
+// runtime as development, so the label survives a single var being unset.
 export function isDevelopmentRuntime() {
-    return process.env.AIMUX_ENV === "development";
+    return (process.env.AIMUX_ENV?.trim() === "development" ||
+        normalizeHome(process.env.AIMUX_HOME) === DEV_HOME ||
+        process.env.AIMUX_DAEMON_PORT?.trim() === DEV_DAEMON_PORT ||
+        optionalEnv(process.env.AIMUX_WEB_APP_URL) === DEV_WEB_APP_URL);
 }
 export function resolveWebAppUrl(override) {
     const value = optionalEnv(override) ??

package/dist/context/context-bridge.js

@@ -9,6 +9,7 @@ import { algorithmicCompact } from "./compactor.js";
 import { debugTurn, debugGit, debugContext, debugCompact } from "../debug.js";
 import { TmuxRuntimeManager } from "../tmux/runtime-manager.js";
 import { classifyToolPane } from "../tool-output-watchers.js";
+import { parseAgentOutput } from "../agent-output-parser.js";
 const git = simpleGit();
 const MAX_LIVE_MD_BYTES = 50 * 1024;
 const MAX_LIVE_MD_LINES = 200;
@@ -243,7 +244,9 @@ export class ContextWatcher {
         debugContext("wrote", `${session.id}/live.md`, snapshot.length);
         const turns = readHistory(session.id, { lastN: 1 });
         if (promptVisible) {
-            const snapshotTurn = normalized.split("\n").slice(-80).join("\n").trim();
+            const blocks = parseAgentOutput(normalized, { tool: session.command }).blocks;
+            const lastResponseBlock = blocks.filter((block) => block.type === "response").at(-1);
+            const snapshotTurn = lastResponseBlock?.text.trim() ?? "";
             if (snapshotTurn) {
                 const lastTurn = turns.at(-1);
                 if (!lastTurn || lastTurn.content !== snapshotTurn) {

package/dist/credentials.js

@@ -3,8 +3,8 @@
 // Populated by `aimux login` (browser flow). The daemon reads this to connect
 // to the relay. The token is a long-lived relay-signed JWT — not a Clerk
 // session token — so it survives daemon restarts and runs for ~90 days.
-import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, chmodSync } from "node:fs";
-import { dirname } from "node:path";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { atomicWrite } from "./atomic-write.js";
 import { getAuthPath } from "./paths.js";
 export function loadCredentials() {
     const path = getAuthPath();
@@ -21,10 +21,7 @@ export function loadCredentials() {
     }
 }
 export function saveCredentials(creds) {
-    const path = getAuthPath();
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
-    chmodSync(path, 0o600);
+    atomicWrite(getAuthPath(), `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
 }
 export function clearCredentials() {
     const path = getAuthPath();

package/dist/daemon.d.ts

@@ -30,6 +30,7 @@ export declare function projectServiceStatus(projectRoot: string): Promise<Proje
 export declare class AimuxDaemon {
     private server;
     private relayClient;
+    private readonly pushThrottle;
     private readonly children;
     private readonly projectEnsurePromises;
     private state;

package/dist/daemon.js

@@ -9,6 +9,7 @@ import { loadMetadataEndpoint } from "./metadata-store.js";
 import { requestJson } from "./http-client.js";
 import { getLoggingConfig, log } from "./debug.js";
 import { RelayClient } from "./relay-client.js";
+import { MobilePushThrottle } from "./mobile-push-throttle.js";
 import { loadCredentials, setRemoteEnabled } from "./credentials.js";
 import { assertRemoteAccessAllowed, parseRemoteActor } from "./remote-access.js";
 const DEFAULT_DAEMON_PORT = 43190;
@@ -328,6 +329,7 @@ export async function projectServiceStatus(projectRoot) {
 export class AimuxDaemon {
     server = null;
     relayClient = null;
+    pushThrottle = new MobilePushThrottle();
     children = new Map();
     projectEnsurePromises = new Map();
     state = loadDaemonState();
@@ -663,6 +665,20 @@ export class AimuxDaemon {
         if (method === "POST" && pathname === "/relay/disable") {
             return { status: 200, body: { ok: true, relay: this.disableRelay() } };
         }
+        if (method === "POST" && pathname === "/internal/push") {
+            if (actor)
+                return { status: 403, body: { ok: false, error: "internal route is loopback-only" } };
+            const payload = body;
+            if (!payload?.title)
+                return { status: 400, body: { ok: false, error: "title is required" } };
+            if (this.relayClient?.getStatus().status !== "connected") {
+                return { status: 200, body: { ok: true, suppressed: true, reason: "relay_unavailable" } };
+            }
+            if (!this.pushThrottle.allow(payload))
+                return { status: 200, body: { ok: true, suppressed: true } };
+            this.relayClient.pushNotification(payload);
+            return { status: 200, body: { ok: true } };
+        }
         if (method === "GET" && pathname === "/projects") {
             const liveById = this.state.projects;
             const projects = listDesktopProjects().map((project) => ({

package/dist/dashboard/index.d.ts

@@ -128,6 +128,7 @@ export interface DashboardViewModel {
     selectedServiceId?: string;
     selectedTeammates: DashboardSession[];
     runtimeLabel?: string;
+    isDevRuntime?: boolean;
     mainCheckout: MainCheckoutInfo;
     worktreeRemoval?: DashboardWorktreeRemovalInfo;
     operationFailures: DashboardOperationFailure[];

package/dist/dashboard/index.js

@@ -15,6 +15,7 @@ export class Dashboard {
         selectedServiceId: undefined,
         selectedTeammates: [],
         runtimeLabel: undefined,
+        isDevRuntime: false,
         mainCheckout: { name: "Main Checkout", branch: "" },
         worktreeRemoval: undefined,
         operationFailures: [],

package/dist/dashboard/targets.js

@@ -1,12 +1,18 @@
 import { isDashboardWindowName } from "../tmux/runtime-manager.js";
 import { getDashboardCommandSpec } from "./command-spec.js";
+import { getRuntimeOwnerId, TMUX_DASHBOARD_OWNER_OPTION, TMUX_RUNTIME_OWNER_OPTION } from "../runtime-owner.js";
 function isUsableDashboardTarget(tmux, projectRoot, dashboardBuildStamp, dashboardTarget) {
     const currentBuildStamp = tmux.getWindowOption(dashboardTarget, "@aimux-dashboard-build");
+    const currentOwner = getRuntimeOwnerId();
+    const targetRuntimeOwner = tmux.getSessionOption(dashboardTarget.sessionName, TMUX_RUNTIME_OWNER_OPTION);
+    const targetDashboardOwner = tmux.getWindowOption(dashboardTarget, TMUX_DASHBOARD_OWNER_OPTION);
     const targetProjectRoot = tmux.getSessionOption(dashboardTarget.sessionName, "@aimux-project-root");
     const paneCommand = tmux.displayMessage("#{pane_current_command}", dashboardTarget.windowId);
     const paneTail = paneCommand === "bash" ? tmux.captureTarget(dashboardTarget, { startLine: -40 }) : "";
     return (tmux.isWindowAlive(dashboardTarget) &&
         targetProjectRoot === projectRoot &&
+        targetRuntimeOwner === currentOwner &&
+        targetDashboardOwner === currentOwner &&
         currentBuildStamp === dashboardBuildStamp &&
         paneCommand !== "cat" &&
         paneCommand !== "tail" &&
@@ -110,11 +116,17 @@ export function resolveDashboardTarget(projectRoot, tmux, options = {}) {
     const openSessionName = tmux.getOpenSessionName(dashboardSession.sessionName, tmux.isInsideTmux());
     const dashboardTarget = tmux.ensureDashboardWindow(openSessionName, projectRoot, dashboardCommand);
     const currentBuildStamp = tmux.getWindowOption(dashboardTarget, "@aimux-dashboard-build");
-    const shouldRespawn = options.forceReload === true || !tmux.isWindowAlive(dashboardTarget) || currentBuildStamp !== dashboardBuildStamp;
+    const currentOwner = getRuntimeOwnerId();
+    const currentDashboardOwner = tmux.getWindowOption(dashboardTarget, TMUX_DASHBOARD_OWNER_OPTION);
+    const shouldRespawn = options.forceReload === true ||
+        !tmux.isWindowAlive(dashboardTarget) ||
+        currentBuildStamp !== dashboardBuildStamp ||
+        currentDashboardOwner !== currentOwner;
     if (shouldRespawn) {
         tmux.respawnWindow(dashboardTarget, dashboardCommand);
-        tmux.setWindowOption(dashboardTarget, "@aimux-dashboard-build", dashboardBuildStamp);
     }
+    tmux.setWindowOption(dashboardTarget, "@aimux-dashboard-build", dashboardBuildStamp);
+    tmux.setWindowOption(dashboardTarget, TMUX_DASHBOARD_OWNER_OPTION, currentOwner);
     return { dashboardSession, dashboardTarget };
 }
 export function openDashboardTarget(projectRoot, tmux, options = {}) {

package/dist/dashboard/ui-state-store.js

@@ -1,4 +1,5 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { writeJsonAtomic } from "../atomic-write.js";
 import { dashboardOrderKey, moveDashboardOrder, orderDashboardServicesForWorktree, orderDashboardSessionsForWorktree, orderDashboardWorktreeGroups, } from "./order.js";
 import { getDashboardClientUiStatePath, getDashboardUiStatePath } from "../paths.js";
 export class DashboardUiStateStore {
@@ -89,8 +90,8 @@ export class DashboardUiStateStore {
             this.flatSessionId = flatSession.id;
         }
         try {
-            writeFileSync(getDashboardUiStatePath(), JSON.stringify(sharedSnapshot, null, 2) + "\n");
-            writeFileSync(getDashboardClientUiStatePath(clientKey), JSON.stringify(clientSnapshot, null, 2) + "\n");
+            writeJsonAtomic(getDashboardUiStatePath(), sharedSnapshot);
+            writeJsonAtomic(getDashboardClientUiStatePath(clientKey), clientSnapshot);
         }
         catch { }
     }

package/dist/last-used.js

@@ -1,7 +1,8 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { getProjectStateDirFor } from "./paths.js";
 import { join } from "node:path";
 import { parseRecencyTimestamp } from "./recency.js";
+import { writeJsonAtomic } from "./atomic-write.js";
 const LAST_USED_VERSION = 1;
 const MAX_RECENT_IDS = 64;
 const EMPTY_STATE = {
@@ -66,7 +67,7 @@ export function compareLastUsed(left, right, rankMap) {
 function persistLastUsedState(projectRoot, state) {
     const dir = getProjectStateDirFor(projectRoot);
     mkdirSync(dir, { recursive: true });
-    writeFileSync(getLastUsedPath(projectRoot), JSON.stringify(state, null, 2));
+    writeJsonAtomic(getLastUsedPath(projectRoot), state);
 }
 function normalizeLastUsedState(state) {
     const items = Object.fromEntries(Object.entries(state.items ?? {}).flatMap(([itemId, value]) => typeof value?.lastUsedAt === "string" ? [[itemId, { lastUsedAt: value.lastUsedAt }]] : []));

package/dist/launcher-env.d.ts

@@ -0,0 +1,4 @@
+type MutableEnv = Record<string, string | undefined>;
+export declare function prepareStableCliEnv(env?: MutableEnv): void;
+export declare function prepareDevCliEnv(env?: MutableEnv): void;
+export {};

package/dist/launcher-env.js

@@ -0,0 +1,70 @@
+import { homedir } from "node:os";
+import { resolve, join } from "node:path";
+const PROD_HOME = join(homedir(), ".aimux");
+const DEV_HOME = join(homedir(), ".aimux-dev");
+const PROD_DAEMON_PORT = "43190";
+const DEV_DAEMON_PORT = "43191";
+const PROD_WEB_APP_URL = "https://aimux.app";
+const DEV_WEB_APP_URL = "http://localhost:8081";
+function normalizeHome(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed === "~")
+        return homedir();
+    if (trimmed.startsWith("~/"))
+        return resolve(homedir(), trimmed.slice(2));
+    return resolve(trimmed);
+}
+function sameHome(value, expected) {
+    const normalized = normalizeHome(value);
+    return normalized !== null && normalized === expected;
+}
+function sameValue(value, expected) {
+    return value?.trim() === expected;
+}
+function blank(value) {
+    return !value?.trim();
+}
+function clearSessionScopedEnv(env) {
+    delete env.AIMUX_METADATA_ENDPOINT_FILE;
+    delete env.AIMUX_SESSION_ID;
+    delete env.AIMUX_SHELL_INTEGRATION_SCRIPT;
+    delete env.AIMUX_TOOL;
+}
+export function prepareStableCliEnv(env = process.env) {
+    const inheritedDevTarget = sameHome(env.AIMUX_HOME, DEV_HOME) ||
+        sameValue(env.AIMUX_DAEMON_PORT, DEV_DAEMON_PORT) ||
+        sameValue(env.AIMUX_ENV, "development") ||
+        sameValue(env.AIMUX_WEB_APP_URL, DEV_WEB_APP_URL);
+    if (blank(env.AIMUX_HOME) || sameHome(env.AIMUX_HOME, DEV_HOME))
+        env.AIMUX_HOME = PROD_HOME;
+    if (blank(env.AIMUX_DAEMON_PORT) || sameValue(env.AIMUX_DAEMON_PORT, DEV_DAEMON_PORT)) {
+        env.AIMUX_DAEMON_PORT = PROD_DAEMON_PORT;
+    }
+    if (blank(env.AIMUX_ENV) || sameValue(env.AIMUX_ENV, "development"))
+        env.AIMUX_ENV = "production";
+    if (blank(env.AIMUX_WEB_APP_URL) || sameValue(env.AIMUX_WEB_APP_URL, DEV_WEB_APP_URL)) {
+        env.AIMUX_WEB_APP_URL = PROD_WEB_APP_URL;
+    }
+    if (inheritedDevTarget)
+        clearSessionScopedEnv(env);
+}
+export function prepareDevCliEnv(env = process.env) {
+    const inheritedStableTarget = sameHome(env.AIMUX_HOME, PROD_HOME) ||
+        sameValue(env.AIMUX_DAEMON_PORT, PROD_DAEMON_PORT) ||
+        sameValue(env.AIMUX_ENV, "production") ||
+        sameValue(env.AIMUX_WEB_APP_URL, PROD_WEB_APP_URL);
+    if (blank(env.AIMUX_HOME) || sameHome(env.AIMUX_HOME, PROD_HOME))
+        env.AIMUX_HOME = DEV_HOME;
+    if (blank(env.AIMUX_DAEMON_PORT) || sameValue(env.AIMUX_DAEMON_PORT, PROD_DAEMON_PORT)) {
+        env.AIMUX_DAEMON_PORT = DEV_DAEMON_PORT;
+    }
+    if (blank(env.AIMUX_ENV) || sameValue(env.AIMUX_ENV, "production"))
+        env.AIMUX_ENV = "development";
+    if (blank(env.AIMUX_WEB_APP_URL) || sameValue(env.AIMUX_WEB_APP_URL, PROD_WEB_APP_URL)) {
+        env.AIMUX_WEB_APP_URL = DEV_WEB_APP_URL;
+    }
+    if (inheritedStableTarget)
+        clearSessionScopedEnv(env);
+}

package/dist/main.js

@@ -20,6 +20,7 @@ import { createThread, listThreadSummaries, markThreadSeen, readMessages, readTh
 import { sendDirectMessage, sendThreadMessage } from "./orchestration.js";
 import { runLoginFlow } from "./login-flow.js";
 import { clearCredentials, loadCredentials, setRemoteEnabled } from "./credentials.js";
+import { takeOverProjectFromOtherOwners } from "./project-takeover.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";
@@ -37,6 +38,7 @@ import { persistProjectRuntimeSnapshotsBeforeTmuxStop } from "./multiplexer/serv
 import { configureLogging, log, resolveLoggingRuntimeConfig } from "./debug.js";
 import { createRuntimeTopologyStore } from "./runtime-core/topology-store.js";
 import { listTopologySessionStates } from "./runtime-core/topology-sessions.js";
+import { reconcileOfflineBackendSessionIds } from "./runtime-core/backend-id-reconcile.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";
@@ -561,6 +563,8 @@ program
         const tmux = new TmuxRuntimeManager();
         ensureTmuxAvailable(tmux);
         if (!tool && !opts.resume && !opts.restore) {
+            await takeOverProjectFromOtherOwners(projectRoot);
+            await ensureDaemonProjectReady(projectRoot);
             const liveDashboard = findLiveDashboardTarget(projectRoot, tmux);
             if (liveDashboard) {
                 tmux.openTarget(liveDashboard.dashboardTarget, {
@@ -2790,16 +2794,23 @@ repairCmd
     const tmux = new TmuxRuntimeManager();
     ensureTmuxAvailable(tmux);
     const result = repairTmuxRuntime(tmux, { projectRoot });
+    const backendReconcile = reconcileOfflineBackendSessionIds(projectRoot);
     if (opts.open) {
         const { dashboardTarget } = resolveDashboardTarget(projectRoot, tmux);
         tmux.openTarget(dashboardTarget, { insideTmux: tmux.isInsideTmux(), alreadyResolved: true });
         exitAfterOpen();
     }
     if (opts.json) {
-        console.log(JSON.stringify(result, null, 2));
+        console.log(JSON.stringify({ ...result, backendReconcile }, null, 2));
         return;
     }
     console.log(renderTmuxRepairResult(result));
+    if (backendReconcile.reconciled.length > 0) {
+        console.log(`Recovered backend session id for ${backendReconcile.reconciled.length} offline agent(s):`);
+        for (const entry of backendReconcile.reconciled) {
+            console.log(`  ${entry.id} -> ${entry.backendSessionId}`);
+        }
+    }
 });
 const metadataCmd = program.command("metadata").description("Push metadata into aimux tmux status integration");
 const metadataTracker = new AgentTracker();
@@ -2927,6 +2938,10 @@ program
     const result = { ok: true, action, sessionId };
     if (payload.session_id) {
         result.backendSessionId = payload.session_id;
+        // No local fallback: this hook is a short-lived CLI process, not the
+        // runtime that owns the session, so it cannot record into topology
+        // directly. A service-down capture gap is closed by reconcile-on-restart.
+        await postLiveProjectServiceJsonOrLocal(projectRoot, "/agents/record-backend-session", { sessionId, backendSessionId: payload.session_id }, () => ({ ok: true })).catch(() => { });
     }
     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));

package/dist/metadata-server.d.ts

@@ -1,6 +1,7 @@
 import { type SessionAlertDisplayContext } from "./alert-display.js";
 import { type MessageKind } from "./threads.js";
 import { type TaskLifecycleResult } from "./orchestration-actions.js";
+import type { LaunchOverride } from "./shell-args.js";
 import type { ParsedAgentOutput } from "./agent-output-parser.js";
 import { ProjectEventBus } from "./project-events.js";
 interface MetadataServerOptions {
@@ -204,7 +205,7 @@ interface MetadataServerOptions {
             sessionId?: string;
             worktreePath?: string;
             open?: boolean;
-            extraArgs?: string[];
+            launchOverride?: LaunchOverride;
         }) => Promise<{
             sessionId: string;
         }> | {
@@ -242,7 +243,7 @@ interface MetadataServerOptions {
             instruction?: string;
             worktreePath?: string;
             open?: boolean;
-            extraArgs?: string[];
+            launchOverride?: LaunchOverride;
         }) => Promise<{
             sessionId: string;
             threadId: string;
@@ -297,6 +298,16 @@ interface MetadataServerOptions {
             status: "graveyard";
             previousStatus: "running" | "offline";
         };
+        recordBackendSessionId?: (input: {
+            sessionId: string;
+            backendSessionId: string;
+        }) => Promise<{
+            sessionId: string;
+            backendSessionId: string;
+        }> | {
+            sessionId: string;
+            backendSessionId: string;
+        };
         sendAgentInput?: (input: {
             sessionId: string;
             text: string;

package/dist/metadata-server.js

@@ -3,6 +3,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getDashboardClientUiStatePath, getPlansDir, getProjectId, getProjectStateDir } from "./paths.js";
+import { writeJsonAtomic } from "./atomic-write.js";
 import { updateSessionMetadata, clearSessionLogs, saveMetadataEndpoint, loadMetadataState, } from "./metadata-store.js";
 import { contextualizeAlertInput, mergeDisplayContext, metadataDisplayContext, } from "./alert-display.js";
 import { notifyAlert } from "./notify.js";
@@ -16,7 +17,7 @@ import { readAllTasks, readTask } from "./tasks.js";
 import { buildWorkflowEntries } from "./workflow.js";
 import { markLastUsed } from "./last-used.js";
 import { formatRelativeRecency } from "./recency.js";
-import { getAttachment, getAttachmentContent } from "./attachment-store.js";
+import { createUploadedAttachment, getAttachment, getAttachmentContent, getAttachmentRecord, } from "./attachment-store.js";
 import { ProjectEventBus } from "./project-events.js";
 import { getProjectServiceManifest } from "./project-service-manifest.js";
 import { applyShellStateTransition } from "./shell-state.js";
@@ -78,7 +79,7 @@ function persistDashboardClientPreference(clientSession, update) {
     }
     catch { }
     update(snapshot);
-    writeFileSync(path, JSON.stringify(snapshot, null, 2) + "\n");
+    writeJsonAtomic(path, snapshot);
 }
 function persistDashboardReturnSelection(tmux, projectRoot, currentClientSession, currentWindowId) {
     persistDashboardClientPreference(currentClientSession, (snapshot) => {
@@ -177,6 +178,16 @@ function sendBytes(res, status, body, mimeType) {
     res.setHeader("connection", "close");
     res.end(body);
 }
+function formatAgentInputWithAttachments(text, attachments) {
+    const trimmedText = text.trim();
+    if (attachments.length === 0)
+        return text;
+    const body = trimmedText || "Please review the attached image file(s).";
+    const attachmentLines = attachments.map((attachment) => {
+        return `- ${attachment.filename} (${attachment.mimeType}, ${attachment.sizeBytes} bytes): ${attachment.contentPath}`;
+    });
+    return `${body}\n\nAttached image files:\n${attachmentLines.join("\n")}`;
+}
 function sendSseEvent(res, event, data) {
     res.write(`event: ${event}\n`);
     res.write(`data: ${JSON.stringify(data)}\n\n`);
@@ -1937,6 +1948,17 @@ export class MetadataServer {
                 send(res, 200, { ok: true, ...result });
                 return;
             }
+            if (req.method === "POST" && url.pathname === "/agents/record-backend-session") {
+                const body = (await readJson(req));
+                if (!this.options.lifecycle?.recordBackendSessionId) {
+                    send(res, 501, { ok: false, error: "backend session recording not supported by this service" });
+                    return;
+                }
+                const result = await this.options.lifecycle.recordBackendSessionId(body);
+                this.options.onChange?.();
+                send(res, 200, { ok: true, ...result });
+                return;
+            }
             if (req.method === "POST" && url.pathname === "/agents/interrupt") {
                 const body = (await readJson(req));
                 if (!this.options.lifecycle?.interruptAgent) {
@@ -1989,19 +2011,53 @@ export class MetadataServer {
                     return;
                 }
                 const text = typeof body.text === "string" ? body.text : "";
-                if (!text.trim()) {
+                const attachmentIds = Array.isArray(body.attachmentIds)
+                    ? body.attachmentIds
+                        .filter((id) => typeof id === "string")
+                        .map((id) => id.trim())
+                        .filter(Boolean)
+                    : [];
+                if (!text.trim() && attachmentIds.length === 0) {
                     send(res, 400, { ok: false, error: "text is required" });
                     return;
                 }
+                const attachments = attachmentIds.map((id) => getAttachmentRecord(id));
+                const missingAttachmentId = attachmentIds.find((_, index) => attachments[index] === null);
+                if (missingAttachmentId) {
+                    send(res, 400, { ok: false, error: `attachment not found: ${missingAttachmentId}` });
+                    return;
+                }
                 if (!this.options.lifecycle?.sendAgentInput) {
                     send(res, 501, { ok: false, error: "agent input not supported by this service" });
                     return;
                 }
-                const result = await this.options.lifecycle.sendAgentInput({ sessionId, text });
+                const formattedText = formatAgentInputWithAttachments(text, attachments.filter((entry) => !!entry));
+                const result = await this.options.lifecycle.sendAgentInput({ sessionId, text: formattedText });
                 this.options.onChange?.();
                 send(res, 200, { ok: true, ...result });
                 return;
             }
+            if (req.method === "POST" && url.pathname === "/attachments") {
+                const body = (await readJson(req));
+                if (typeof body.filename !== "string" ||
+                    typeof body.mimeType !== "string" ||
+                    typeof body.dataBase64 !== "string") {
+                    send(res, 400, { ok: false, error: "filename, mimeType, and dataBase64 are required" });
+                    return;
+                }
+                try {
+                    const attachment = createUploadedAttachment({
+                        filename: body.filename,
+                        mimeType: body.mimeType,
+                        dataBase64: body.dataBase64,
+                    });
+                    send(res, 200, { ok: true, attachment });
+                }
+                catch (error) {
+                    send(res, 400, { ok: false, error: error instanceof Error ? error.message : "invalid attachment" });
+                }
+                return;
+            }
             const attachmentContentMatch = url.pathname.match(/^\/attachments\/([^/]+)\/content$/);
             if (req.method === "GET" && attachmentContentMatch) {
                 const content = getAttachmentContent(decodeURIComponent(attachmentContentMatch[1] || ""));

package/dist/metadata-store.js

@@ -1,6 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { writeJsonAtomic } from "./atomic-write.js";
+import { quarantineCorruptFile, writeJsonAtomic, writeTextAtomic } from "./atomic-write.js";
 import { getProjectStateDir, getProjectStateDirFor } from "./paths.js";
 function ensureParent(path) {
     mkdirSync(dirname(path), { recursive: true });
@@ -21,6 +21,7 @@ function loadJson(path, fallback) {
         return JSON.parse(readFileSync(path, "utf-8"));
     }
     catch {
+        quarantineCorruptFile(path);
         return fallback;
     }
 }
@@ -94,7 +95,7 @@ export function saveMetadataEndpoint(endpoint, projectRoot) {
     saveJson(endpointPathFor(projectRoot), endpoint);
     const textPath = endpointTextPathFor(projectRoot);
     ensureParent(textPath);
-    writeFileSync(textPath, `http://${endpoint.host}:${endpoint.port}\n`);
+    writeTextAtomic(textPath, `http://${endpoint.host}:${endpoint.port}\n`);
 }
 export function removeMetadataEndpoint(projectRoot) {
     try {

package/dist/mobile-push-bridge.d.ts

@@ -0,0 +1,8 @@
+import type { AlertEvent } from "./project-events.js";
+/**
+ * Forwards an alert that already passed desktop notification gating to the
+ * daemon, which relays it to the owner's mobile devices. Fire-and-forget: the
+ * daemon owns the single relay connection, so the project service hands off and
+ * never blocks the alert path on push delivery.
+ */
+export declare function forwardAlertToMobilePush(event: AlertEvent): void;

package/dist/mobile-push-bridge.js

@@ -0,0 +1,22 @@
+import { requestDaemonJson } from "./daemon.js";
+/**
+ * Forwards an alert that already passed desktop notification gating to the
+ * daemon, which relays it to the owner's mobile devices. Fire-and-forget: the
+ * daemon owns the single relay connection, so the project service hands off and
+ * never blocks the alert path on push delivery.
+ */
+export function forwardAlertToMobilePush(event) {
+    void requestDaemonJson("/internal/push", {
+        method: "POST",
+        body: JSON.stringify({
+            title: event.title || "aimux",
+            body: event.message || event.sessionId || event.kind,
+            kind: event.kind,
+            sessionId: event.sessionId,
+            projectId: event.projectId,
+            projectRoot: process.cwd(),
+            dedupeKey: event.dedupeKey,
+        }),
+        headers: { "content-type": "application/json" },
+    }).catch(() => { });
+}

package/dist/mobile-push-throttle.d.ts

@@ -0,0 +1,23 @@
+export interface ThrottleInput {
+    dedupeKey?: string;
+    sessionId?: string;
+    kind?: string;
+    title?: string;
+    body?: string;
+}
+/**
+ * In-memory guard for outbound mobile pushes. Collapses identical alerts
+ * re-emitted within a TTL window (chatty idle/needs_input polling) and caps the
+ * push rate per session so one runaway agent cannot flood the device.
+ */
+export declare class MobilePushThrottle {
+    private readonly dedupeTtlMs;
+    private readonly sessionLimit;
+    private readonly sessionWindowMs;
+    private readonly now;
+    private readonly lastByKey;
+    private readonly sessionHits;
+    constructor(dedupeTtlMs?: number, sessionLimit?: number, sessionWindowMs?: number, now?: () => number);
+    allow(input: ThrottleInput): boolean;
+    private prune;
+}