@cydm/happy-elves 0.1.0-beta.70 → 0.1.0-beta.71

package/README.md

@@ -8,7 +8,7 @@ Public beta CLI for Happy Elves.
 happy-elves start
 ```
 
-Existing workspace recovery uses a one-time invite from Settings → Browsers → Add:
+Reconnect this Device to an existing Account with a one-time invite from Settings → Devices → Add Device (the CLI command name is retained for compatibility):
 
 ```bash
 happy-elves remote join-controller --url "<invite-url>" --recover-controller --json

package/apps/cli/dist/commands/account.js

@@ -261,7 +261,7 @@ export async function handleAccount({ domain, action, flags }) {
                 response = await fetch(`${relayUrl}/api/pairing/start`, {
                     method: "POST",
                     headers: { "content-type": "application/json" },
-                    body: JSON.stringify({ deviceId, deviceName }),
+                    body: JSON.stringify({ deviceId, deviceName, surface: "cli" }),
                     signal: AbortSignal.timeout(accountCreateRelayTimeoutMs),
                 });
             }
@@ -292,7 +292,13 @@ export async function handleAccount({ domain, action, flags }) {
                 expiresAt: paired.expiresAt,
             };
         });
-        ok("account.create", created);
+        if (flags["reveal-secrets"] === true) {
+            ok("account.create", created);
+        }
+        else {
+            const { controllerToken: _controllerToken, accountSecret: _accountSecret, ...safeCreated } = created;
+            ok("account.create", safeCreated);
+        }
         return true;
     }
     if (domain === "account" && action === "reset") {

package/apps/cli/dist/commands/config.js

@@ -24,7 +24,7 @@ export async function handleConfig({ domain, action, flags }) {
             const redacted = redactedControllerConfig(config);
             console.log(`Config: ${configPath}`);
             console.log(`Relay: ${redacted.relayUrl}`);
-            console.log(`Controller token: ${redacted.hasControllerToken ? "configured" : "missing"}`);
+            console.log(`Device credential: ${redacted.hasControllerToken ? "configured" : "missing"}`);
             console.log(`Account secret: ${redacted.hasAccountSecret ? "configured" : "missing"}`);
             return true;
         }

package/apps/cli/dist/commands/daemon.js

@@ -1,7 +1,8 @@
 import { createHash, timingSafeEqual } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
-import { assertLocalDaemonVerified, canonicalRelayUrl, cliErrorFromFetch, CliError, compactText, ControllerClient, configDir, configPath, daemonPidPath, deriveOrchestration, diagnoseInstallation, emitDoctorResult, idleSessionStatuses, localDaemonStatus, ok, parsePairingClaimResponse, randomId, readConfig, readDaemonConfig, readLocalAuditLog, readRelayJson, redactedDaemonConfig, requirePositional, requireRelayUrl, requireString, showMachine, spawnDaemonStart, stopLocalDaemon, throwRelayHttpError, wantsJson, withAccountConfigTransaction } from "./lib/index.js";
+import { daemonLifecycleRequestIdV1Schema, } from "../../../../packages/shared/dist/index.js";
+import { assertLocalDaemonRuntimeMatchesConfig, assertLocalDaemonVerified, canonicalRelayUrl, cliErrorFromFetch, CliError, compactText, ControllerClient, configDir, configPath, daemonPidPath, deriveOrchestration, diagnoseInstallation, emitDoctorResult, ensureDaemonRunning, idleSessionStatuses, localDaemonStatus, ok, parsePairingClaimResponse, randomId, readConfig, readDaemonConfig, readDaemonProjectionBaseline, readLocalAuditLog, readOptionalControllerConfig, readRelayJson, redactedDaemonConfig, requirePositional, requireRelayUrl, requireString, showMachine, startDaemonTimeoutMs, stopLocalDaemon, stopSpawnedDaemon, throwRelayHttpError, waitForDaemonReadiness, waitForDaemonSelfReadiness, wantsJson, withAccountConfigTransaction } from "./lib/index.js";
 function positiveLimit(flags, fallback) {
     const value = flags.limit;
     if (value === undefined)
@@ -28,6 +29,114 @@ async function boundedMap(values, concurrency, map) {
 function overviewUnsupported(error) {
     return error.code === "OVERVIEW_UNSUPPORTED";
 }
+function assertControllerCanObserveDaemon(controllerConfig, daemonConfig) {
+    if (canonicalRelayUrl(controllerConfig.relayUrl, "Controller config") !==
+        canonicalRelayUrl(daemonConfig.relayUrl, "Daemon config") ||
+        !pairSecretsEqual(controllerConfig.accountSecret, daemonConfig.accountSecret)) {
+        throw new CliError("Controller and daemon configurations belong to different workspaces. Local daemon readiness cannot be verified and no process was changed.", "CONFIG_SPLIT_BRAIN");
+    }
+}
+async function waitForLocalDaemonReadiness(client, config, baseline, daemon, requireFreshProjection) {
+    try {
+        if (!client) {
+            const local = await localDaemonStatus();
+            assertLocalDaemonVerified(local);
+            if (!local.running) {
+                throw new CliError("Daemon exited before its local runtime identity became ready. Run happy-elves daemon doctor and happy-elves daemon logs.", "DAEMON_START_FAILED");
+            }
+            await assertLocalDaemonRuntimeMatchesConfig(config);
+            await waitForDaemonSelfReadiness(config, daemon.instanceGeneration, { timeoutMs: startDaemonTimeoutMs });
+            return { local, relayAuthenticated: "verified" };
+        }
+        const readiness = await waitForDaemonReadiness(client, config.machineId, {
+            baseline,
+            expectedInstanceGeneration: daemon.instanceGeneration,
+            requireFreshProjection,
+            timeoutMs: startDaemonTimeoutMs,
+        });
+        if (readiness.phase === "process-exited" || readiness.phase === "owner-changed") {
+            throw new CliError("Daemon exited before it authenticated with the relay. Run happy-elves daemon doctor and happy-elves daemon logs.", "DAEMON_START_FAILED");
+        }
+        if (readiness.phase !== "relay-authenticated" || !readiness.machine?.online) {
+            const relayDetail = readiness.lastRelayErrorCode ? ` Last relay error: ${readiness.lastRelayErrorCode}.` : "";
+            throw new CliError(`Daemon is running, but it did not authenticate with the relay before the startup deadline.${relayDetail} Run happy-elves daemon doctor and happy-elves daemon logs.`, "DAEMON_ONLINE_TIMEOUT");
+        }
+        return { ...readiness, relayAuthenticated: "verified" };
+    }
+    catch (error) {
+        if (daemon.startedHandle) {
+            try {
+                await stopSpawnedDaemon(daemon.startedHandle);
+            }
+            catch (cleanupError) {
+                throw new CliError(`Daemon readiness failed and its owned child could not be cleaned up: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`, "DAEMON_START_CLEANUP_FAILED");
+            }
+        }
+        throw error;
+    }
+}
+async function remoteDaemonLifecycle(flags, action) {
+    const machineId = requireString(flags, "machine");
+    if (flags["request-id"] === true)
+        throw new CliError("Missing --request-id value", "MISSING_ARGUMENT");
+    const explicitRequestId = typeof flags["request-id"] === "string" ? flags["request-id"] : undefined;
+    const requestId = explicitRequestId ?? randomId("life");
+    if (!daemonLifecycleRequestIdV1Schema.safeParse(requestId).success) {
+        throw new CliError("Invalid --request-id", "INVALID_ARGUMENT");
+    }
+    const config = await readConfig(flags);
+    const client = new ControllerClient(config);
+    if (explicitRequestId !== undefined) {
+        const retained = await client.queryDaemonLifecycleOperation(machineId, requestId);
+        if (retained) {
+            const semanticsMatch = retained.daemonId === machineId &&
+                retained.action === action &&
+                (action === "upgrade" ? retained.channel === "beta" : retained.channel === undefined);
+            if (!semanticsMatch) {
+                throw new CliError(`Lifecycle request id is already bound to another operation: ${requestId}`, "REQUEST_ID_CONFLICT");
+            }
+            ok(`daemon.${action}`, { operation: retained }, { requestId, machineId });
+            return;
+        }
+    }
+    const snapshot = await client.snapshot();
+    const matches = snapshot.machines.filter((machine) => machine.id === machineId);
+    const machine = matches[0];
+    if (!machine)
+        throw new CliError(`Daemon not found: ${machineId}`, "MACHINE_NOT_FOUND");
+    if (matches.length !== 1) {
+        throw new CliError(`Relay returned duplicate Daemon identities: ${machineId}`, "RELAY_RESPONSE_INVALID");
+    }
+    if (!machine.online)
+        throw new CliError(`Daemon is offline: ${machineId}`, "MACHINE_OFFLINE");
+    const capability = machine.capabilities.daemonLifecycleV1;
+    const expectedInstanceGeneration = machine.capabilities.daemonInstanceGeneration;
+    const supported = capability !== undefined &&
+        expectedInstanceGeneration !== undefined &&
+        capability[action] &&
+        (action !== "upgrade" || (capability.installKind === "npm-global" && capability.channel === "beta"));
+    if (!supported) {
+        throw new CliError(`Daemon does not support remote ${action}: ${machineId}`, "DAEMON_LIFECYCLE_UNSUPPORTED");
+    }
+    const request = action === "upgrade"
+        ? {
+            version: 1,
+            requestId,
+            daemonId: machineId,
+            expectedInstanceGeneration,
+            action,
+            channel: "beta",
+        }
+        : {
+            version: 1,
+            requestId,
+            daemonId: machineId,
+            expectedInstanceGeneration,
+            action,
+        };
+    const operation = await client.startDaemonLifecycleOperation(request);
+    ok(`daemon.${action}`, { operation }, { requestId, machineId });
+}
 async function daemonOverview(client, input) {
     try {
         const sessions = [];
@@ -157,8 +266,8 @@ export async function handleDaemon({ domain, action, flags }) {
             console.log(`Config: ${path.join(configDir, "daemon.json")}`);
             console.log(`Relay: ${redacted.relayUrl}`);
             console.log(`Account: ${redacted.accountId}`);
-            console.log(`Machine: ${redacted.machineName} (${redacted.machineId})`);
-            console.log(`Machine token: ${redacted.hasMachineToken ? "configured" : "missing"}`);
+            console.log(`Daemon: ${redacted.machineName} (${redacted.machineId})`);
+            console.log(`Daemon credential: ${redacted.hasMachineToken ? "configured" : "missing"}`);
             console.log(`Account secret: ${redacted.hasAccountSecret ? "configured" : "missing"}`);
             return true;
         }
@@ -200,20 +309,25 @@ export async function handleDaemon({ domain, action, flags }) {
         return true;
     }
     if (domain === "daemon" && action === "start") {
-        const status = await localDaemonStatus();
-        assertLocalDaemonVerified(status);
-        if (status.running) {
-            const data = { ...status, started: false };
-            if (wantsJson(flags))
-                ok("daemon.start", data);
-            else
-                writeHumanDaemonStartOutput(data);
-            return true;
-        }
-        await readDaemonConfig();
-        const startArgs = typeof flags.relay === "string" ? ["--relay", flags.relay] : [];
-        const pid = spawnDaemonStart(startArgs);
-        const data = { pid, pidPath: daemonPidPath, started: true };
+        assertLocalDaemonVerified(await localDaemonStatus());
+        const config = await readDaemonConfig();
+        assertDaemonRelayOverrideMatches(flags, config);
+        const controllerConfig = await readOptionalControllerConfig();
+        if (controllerConfig)
+            assertControllerCanObserveDaemon(controllerConfig, config);
+        const client = controllerConfig ? new ControllerClient(controllerConfig) : undefined;
+        const baseline = client
+            ? await readDaemonProjectionBaseline(client, config.machineId, { timeoutMs: startDaemonTimeoutMs })
+            : undefined;
+        const daemon = await ensureDaemonRunning(config);
+        const readiness = await waitForLocalDaemonReadiness(client, config, baseline, daemon, daemon.started);
+        const data = {
+            ...readiness.local,
+            started: daemon.started,
+            machineId: readiness.machine?.id ?? config.machineId,
+            relayAuthenticated: readiness.relayAuthenticated,
+            ...(readiness.relayAuthenticated === "verified" ? { online: true } : {}),
+        };
         if (wantsJson(flags))
             ok("daemon.start", data);
         else
@@ -224,12 +338,43 @@ export async function handleDaemon({ domain, action, flags }) {
         ok("daemon.stop", await stopLocalDaemon());
         return true;
     }
+    if (domain === "daemon" && action === "restart" && flags.machine === true) {
+        throw new CliError("Missing --machine value", "MISSING_ARGUMENT");
+    }
+    if (domain === "daemon" && action === "restart" && typeof flags.machine === "string") {
+        await remoteDaemonLifecycle(flags, "restart");
+        return true;
+    }
+    if (domain === "daemon" && action === "upgrade") {
+        await remoteDaemonLifecycle(flags, "upgrade");
+        return true;
+    }
     if (domain === "daemon" && action === "restart") {
-        await readDaemonConfig();
+        assertLocalDaemonVerified(await localDaemonStatus());
+        const config = await readDaemonConfig();
+        assertDaemonRelayOverrideMatches(flags, config);
+        const controllerConfig = await readOptionalControllerConfig();
+        if (controllerConfig)
+            assertControllerCanObserveDaemon(controllerConfig, config);
+        const client = controllerConfig ? new ControllerClient(controllerConfig) : undefined;
+        const baseline = client
+            ? await readDaemonProjectionBaseline(client, config.machineId, { timeoutMs: startDaemonTimeoutMs })
+            : undefined;
         const stop = await stopLocalDaemon();
-        const startArgs = typeof flags.relay === "string" ? ["--relay", flags.relay] : [];
-        const pid = spawnDaemonStart(startArgs);
-        ok("daemon.restart", { stop, startedPid: pid, pidPath: daemonPidPath });
+        if (stop.running || stop.alive) {
+            throw new CliError("Daemon did not stop before the restart deadline; no replacement process was started.", "DAEMON_STOP_FAILED");
+        }
+        const daemon = await ensureDaemonRunning(config);
+        const readiness = await waitForLocalDaemonReadiness(client, config, baseline, daemon, true);
+        ok("daemon.restart", {
+            stop,
+            startedPid: daemon.startedPid ?? readiness.local.pid,
+            pidPath: daemonPidPath,
+            local: readiness.local,
+            machineId: readiness.machine?.id ?? config.machineId,
+            relayAuthenticated: readiness.relayAuthenticated,
+            ...(readiness.relayAuthenticated === "verified" ? { online: true } : {}),
+        });
         return true;
     }
     if (domain === "daemon" && action === "status" && flags.local === true) {
@@ -264,7 +409,7 @@ export async function handleDaemon({ domain, action, flags }) {
         const overview = await daemonOverview(client, { machineId: machineFilter, includeSessions, all, limit, cursor });
         const machines = overview.machines;
         if (machineFilter && machines.length === 0)
-            throw new CliError("Machine not found", "MACHINE_NOT_FOUND");
+            throw new CliError("Daemon not found", "MACHINE_NOT_FOUND");
         const projectedMachines = includeSessions
             ? await Promise.all((await client.snapshot()).machines
                 .filter((machine) => machines.some((summary) => summary.id === machine.id))
@@ -322,9 +467,9 @@ export async function handleDaemon({ domain, action, flags }) {
             },
         };
         if (!wantsJson(flags)) {
-            console.log(`Relay: ${data.relayUrl} ${data.relayReachable ? "ok" : "unreachable"}`);
+            console.log(`Account: ${data.relayReachable ? "connected" : "unavailable"}`);
             console.log(data.local.running ? `Local daemon: running${data.local.pid ? ` pid ${data.local.pid}` : ""}` : "Local daemon: stopped");
-            console.log(`Machines: ${data.summary.onlineMachineCount}/${data.summary.machineCount} online`);
+            console.log(`Daemons: ${data.summary.onlineMachineCount}/${data.summary.machineCount} online`);
             console.log(`Sessions: ${data.summary.sessionCount} total, ${data.summary.runningSessionCount} running`);
             for (const machine of data.machines) {
                 console.log(`- ${machine.name} (${machine.machineId}) ${machine.online ? "online" : "offline"}`);
@@ -333,7 +478,7 @@ export async function handleDaemon({ domain, action, flags }) {
             }
             if (includeSessions) {
                 for (const session of projectedSessions) {
-                    console.log(`- ${session.sessionId}  ${session.status}  ${session.orchestration.state}  ${session.agent}  machine:${session.machineId}`);
+                    console.log(`- ${session.sessionId}  ${session.status}  ${session.orchestration.state}  ${session.agent}  daemon:${session.machineId}`);
                 }
                 console.log(`Page: ${overview.page.returned} of ${overview.page.total} sessions${overview.page.hasMore ? "; more available" : "; complete"}`);
                 if (overview.page.nextCursor)
@@ -358,6 +503,16 @@ function writeHumanDaemonStartOutput(data) {
     else {
         console.log(`Daemon is already running${data.pid ? ` (pid ${data.pid})` : ""}.`);
     }
+    if (data.relayAuthenticated === "unverified") {
+        console.log("Local daemon identity is ready; relay authentication was not verified because this host has no matching Device credential.");
+    }
     console.log("This command manages only the paired background daemon; it does not open a browser page.");
     console.log("For setup or browser onboarding, run: happy-elves start");
 }
+function assertDaemonRelayOverrideMatches(flags, config) {
+    if (typeof flags.relay !== "string")
+        return;
+    if (canonicalRelayUrl(flags.relay) === canonicalRelayUrl(config.relayUrl))
+        return;
+    throw new CliError("daemon start/restart cannot change the enrolled Account. Use a one-time Re-enroll invite from the Account UI.", "CONFIG_SPLIT_BRAIN");
+}

package/apps/cli/dist/commands/gateway.js

@@ -1,13 +1,16 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { assertLocalDaemonVerified, CliError, configDir, daemonPidPath, localDaemonStatus, ok, parseCsvFlag, randomId, requirePositional, requireString, wantsJson, } from "./lib/index.js";
+import { ControllerClient } from "../../../../packages/client/dist/index.js";
+import { assertLocalDaemonVerified, CliError, configDir, daemonPidPath, localDaemonStatus, ok, parseCsvFlag, randomId, readConfig, requirePositional, requireString, wantsJson, } from "./lib/index.js";
+import { canonicalizeGatewayIdentityInputV1, } from "../../../../packages/shared/dist/index.js";
 import { gatewayStateFootprint, gatewayStateFootprintIsEmpty, gatewaySourceStateDigestV1, inspectGatewayStoreArtifacts, readGatewayStateFile, readGatewayStoreFile, repairGatewayStoreArtifacts, updateGatewayStoreFile, updateGatewayStoresFile, } from "../../../../packages/shared/dist/node/gateway-store.js";
 const defaultGatewayInboundMode = "mention";
 const defaultGatewayProcessingReaction = {
     enabled: true,
     emojiType: "Typing",
 };
+const defaultNewGatewayPermissionMode = "approve-reads";
 const gatewayConfigPath = path.join(configDir, "gateways.json");
 const gatewayStatePath = path.join(configDir, "gateway-state.json");
 const telegramApiBase = "https://api.telegram.org";
@@ -15,6 +18,12 @@ const telegramGetMeTimeoutMs = 10_000;
 export async function handleGateway({ domain, action, positional, flags }) {
     if (domain !== "gateway")
         return false;
+    if (flags.machine !== undefined) {
+        if (typeof flags.machine !== "string" || !flags.machine.trim()) {
+            throw new CliError("Missing value for --machine", "MISSING_ARGUMENT");
+        }
+        return await handleRemoteGateway(action, positional, flags, flags.machine.trim());
+    }
     if (action === "store" && positional[0] === "inspect") {
         const inspection = await inspectGatewayStoreArtifacts({
             configPath: gatewayConfigPath,
@@ -60,7 +69,7 @@ export async function handleGateway({ domain, action, positional, flags }) {
             }
             for (const gateway of store.gateways) {
                 const destination = gateway.defaultDestination ? ` chat:${gateway.defaultDestination.platformChatId}` : "";
-                console.log(`${gateway.id}  ${gateway.enabled ? "enabled" : "disabled"}  ${gateway.platform}  inbound:${gateway.inboundMode}  agent:${gateway.defaultAgent}${destination}`);
+                console.log(`${gateway.id}  ${gateway.enabled ? "enabled" : "disabled"}  ${gateway.platform}  inbound:${gateway.inboundMode}  permission:${gateway.permissionMode ?? "approve-all"}  agent:${gateway.defaultAgent}${destination}`);
             }
             return true;
         }
@@ -88,6 +97,7 @@ export async function handleGateway({ domain, action, positional, flags }) {
                 inboundMode: inboundModeFlag(flags, defaultGatewayInboundMode),
                 processingReaction: processingReactionFromFlags(flags, defaultGatewayProcessingReaction),
                 allowAllUsers: flags["allow-all-users"] === true,
+                permissionMode: permissionModeFlag(flags, defaultNewGatewayPermissionMode),
                 identities: [],
                 createdAt: now,
                 updatedAt: now,
@@ -120,6 +130,7 @@ export async function handleGateway({ domain, action, positional, flags }) {
             console.log(`inbound: ${gateway.inboundMode}`);
             console.log(`reaction: ${gateway.processingReaction.enabled ? gateway.processingReaction.emojiType : "disabled"}`);
             console.log(`default: ${gateway.defaultAgent} ${gateway.defaultCwd}`);
+            console.log(`permission: ${gateway.permissionMode ?? "approve-all"}`);
             if (gateway.defaultDestination)
                 console.log(`default chat: ${gateway.defaultDestination.platformChatId}`);
             console.log(`identities: ${gateway.identities.length}`);
@@ -309,6 +320,7 @@ export async function handleGateway({ domain, action, positional, flags }) {
                     defaultCwd: process.cwd(),
                     inboundMode: defaultGatewayInboundMode,
                     processingReaction: { ...defaultGatewayProcessingReaction },
+                    permissionMode: defaultNewGatewayPermissionMode,
                     identities: [],
                     createdAt: now,
                 }),
@@ -356,17 +368,27 @@ export async function handleGateway({ domain, action, positional, flags }) {
         const platformUserId = stringFlag(flags, "platform-user") ?? stringFlag(flags, "user");
         if (!platformUserId)
             throw new CliError("Missing --platform-user <id>", "MISSING_ARGUMENT");
-        const allowedActions = parseCsvFlag(flags.actions) ?? ["session.create", "session.run"];
         const allowedSessions = parseCsvFlag(flags.sessions);
+        const allowedActions = parseCsvFlag(flags.actions) ?? (allowedSessions?.length ? ["session.run"] : ["session.create", "session.run"]);
+        let canonicalIdentity;
+        try {
+            canonicalIdentity = canonicalizeGatewayIdentityInputV1({
+                platformUserId,
+                ...(stringFlag(flags, "display-name") ? { displayName: stringFlag(flags, "display-name") } : {}),
+                allowedActions,
+                ...(allowedSessions ? { allowedSessions } : {}),
+            });
+        }
+        catch (error) {
+            throw new CliError(error instanceof Error ? error.message : "Gateway identity is invalid", "GATEWAY_IDENTITY_INVALID");
+        }
         const result = await updateGatewayStoreFile(gatewayConfigPath, (store) => {
             const gateway = requireGateway(store, gatewayId);
             const existingGrant = gateway.identities.find((identity) => identity.platformUserId === platformUserId);
             const grant = {
                 ...existingGrant,
-                platformUserId,
-                displayName: stringFlag(flags, "display-name"),
-                allowedActions,
-                allowedSessions,
+                ...canonicalIdentity,
+                allowedSessions: canonicalIdentity.allowedSessions,
             };
             const updated = {
                 ...gateway,
@@ -488,6 +510,197 @@ export async function handleGateway({ domain, action, positional, flags }) {
     }
     return false;
 }
+async function handleRemoteGateway(action, positional, flags, machineId) {
+    const client = new ControllerClient(await readConfig(flags));
+    if (action === "list") {
+        const result = await client.listGateways(machineId);
+        if (!wantsJson(flags)) {
+            if (result.gateways.length === 0)
+                console.log(`No gateways on Daemon ${machineId}.`);
+            for (const gateway of result.gateways)
+                printRemoteGateway(gateway);
+        }
+        else {
+            ok("gateway.list", result, { machineId });
+        }
+        return true;
+    }
+    if (action === "status") {
+        const gatewayId = requirePositional(positional[0], "gatewayId");
+        const gateway = await client.getGateway(machineId, gatewayId);
+        if (!wantsJson(flags))
+            printRemoteGateway(gateway, true);
+        else
+            ok("gateway.status", { machineId, gateway }, { machineId });
+        return true;
+    }
+    if (action === "create") {
+        const platform = platformFlag(flags);
+        const id = stringFlag(flags, "id") ?? randomId("gw");
+        const defaultChatId = stringFlag(flags, "default-chat-id");
+        const gateway = await client.createGateway(machineId, {
+            id,
+            platform,
+            name: stringFlag(flags, "name") ?? `${platform} gateway`,
+            defaultAgent: stringFlag(flags, "default-agent") ?? stringFlag(flags, "agent") ?? "codex",
+            defaultCwd: stringFlag(flags, "default-cwd") ?? stringFlag(flags, "cwd") ?? process.cwd(),
+            ...(defaultChatId ? { defaultDestination: { platformChatId: defaultChatId, contextKind: "main" } } : {}),
+            inboundMode: inboundModeFlag(flags, defaultGatewayInboundMode),
+            processingReaction: processingReactionFromFlags(flags, defaultGatewayProcessingReaction),
+            allowAllUsers: allowAllUsersFlag(flags, false),
+            permissionMode: permissionModeFlag(flags, defaultNewGatewayPermissionMode),
+        }, { ...(stringFlag(flags, "request-id") ? { requestId: stringFlag(flags, "request-id") } : {}) });
+        if (!wantsJson(flags))
+            console.log(`Created gateway ${gateway.id} on Daemon ${machineId}.`);
+        else
+            ok("gateway.create", { machineId, gateway }, { machineId });
+        return true;
+    }
+    if (action === "config" && positional[0] === "set") {
+        const gatewayId = requirePositional(positional[1], "gatewayId");
+        const current = await client.getGateway(machineId, gatewayId);
+        const defaultChatId = stringFlag(flags, "default-chat-id");
+        if (flags["clear-default-chat"] === true && defaultChatId) {
+            throw new CliError("Use only one of --default-chat-id or --clear-default-chat", "INVALID_ARGUMENT");
+        }
+        const gateway = await client.updateGatewayConfig(machineId, gatewayId, {
+            name: stringFlag(flags, "name") ?? current.name,
+            enabled: enabledFlag(flags, current.enabled),
+            inboundMode: inboundModeFlag(flags, current.inboundMode),
+            processingReaction: processingReactionFromFlags(flags, current.processingReaction),
+            defaultAgent: stringFlag(flags, "default-agent") ?? stringFlag(flags, "agent") ?? current.defaultAgent,
+            defaultCwd: stringFlag(flags, "default-cwd") ?? stringFlag(flags, "cwd") ?? current.defaultCwd,
+            allowAllUsers: allowAllUsersFlag(flags, current.allowAllUsers),
+            permissionMode: permissionModeFlag(flags, current.permissionMode ?? "approve-all"),
+            ...(flags["clear-default-chat"] === true
+                ? { defaultDestination: null }
+                : defaultChatId
+                    ? { defaultDestination: { platformChatId: defaultChatId, contextKind: "main" } }
+                    : current.defaultDestination
+                        ? { defaultDestination: current.defaultDestination }
+                        : {}),
+        });
+        if (!wantsJson(flags))
+            console.log(`Updated gateway ${gatewayId} on Daemon ${machineId}.`);
+        else
+            ok("gateway.config.set", { machineId, gateway }, { machineId });
+        return true;
+    }
+    if (action === "secret" && positional[0] === "set") {
+        const gatewayId = requirePositional(positional[1], "gatewayId");
+        const platform = platformFlag(flags);
+        const secret = platform === "telegram"
+            ? { platform, botToken: botTokenFlag(flags) }
+            : platform === "feishu"
+                ? { platform, appId: requireString(flags, "app-id"), appSecret: appSecretFlag(flags), domain: domainFlag(flags) }
+                : { platform };
+        const gateway = await client.setGatewaySecret(machineId, gatewayId, secret);
+        if (!wantsJson(flags))
+            console.log(`Saved gateway secret for ${gatewayId} on Daemon ${machineId}.`);
+        else
+            ok("gateway.secret.set", { machineId, gatewayId, platform, hasSecret: gateway.hasSecret }, { machineId });
+        return true;
+    }
+    if (action === "identity" && positional[0] === "allow") {
+        const gatewayId = requirePositional(positional[1], "gatewayId");
+        const platformUserId = stringFlag(flags, "platform-user") ?? stringFlag(flags, "user");
+        if (!platformUserId)
+            throw new CliError("Missing --platform-user <id>", "MISSING_ARGUMENT");
+        const allowedSessions = parseCsvFlag(flags.sessions);
+        const allowedActions = parseCsvFlag(flags.actions) ?? (allowedSessions?.length ? ["session.run"] : ["session.create", "session.run"]);
+        let identity;
+        try {
+            identity = canonicalizeGatewayIdentityInputV1({
+                platformUserId,
+                ...(stringFlag(flags, "display-name") ? { displayName: stringFlag(flags, "display-name") } : {}),
+                allowedActions,
+                ...(allowedSessions ? { allowedSessions } : {}),
+            });
+        }
+        catch (error) {
+            throw new CliError(error instanceof Error ? error.message : "Gateway identity is invalid", "GATEWAY_IDENTITY_INVALID");
+        }
+        const gateway = await client.upsertGatewayIdentity(machineId, gatewayId, identity);
+        if (!wantsJson(flags))
+            console.log(`Allowed ${platformUserId} on gateway ${gatewayId} (Daemon ${machineId}).`);
+        else
+            ok("gateway.identity.allow", { machineId, gateway, identity }, { machineId });
+        return true;
+    }
+    if (action === "identity" && positional[0] === "remove") {
+        const gatewayId = requirePositional(positional[1], "gatewayId");
+        const platformUserId = stringFlag(flags, "platform-user") ?? stringFlag(flags, "user");
+        if (!platformUserId)
+            throw new CliError("Missing --platform-user <id>", "MISSING_ARGUMENT");
+        const gateway = await client.removeGatewayIdentity(machineId, gatewayId, platformUserId);
+        if (!wantsJson(flags))
+            console.log(`Removed ${platformUserId} from gateway ${gatewayId} (Daemon ${machineId}).`);
+        else
+            ok("gateway.identity.remove", { machineId, gateway, removedPlatformUserId: platformUserId }, { machineId });
+        return true;
+    }
+    if (action === "binding" && positional[0] === "list") {
+        const gatewayId = requirePositional(positional[1], "gatewayId");
+        const result = await client.listGatewayBindings(machineId, gatewayId);
+        if (!wantsJson(flags)) {
+            if (result.bindings.length === 0)
+                console.log(`No bindings for gateway ${gatewayId} on Daemon ${machineId}.`);
+            for (const binding of result.bindings) {
+                const thread = binding.contextKind === "thread" ? ` thread:${binding.contextKey ?? ""}` : "";
+                console.log(`${binding.sessionId}  chat:${binding.platformChatId}${thread}  agent:${binding.agent}  cwd:${binding.cwd}`);
+            }
+        }
+        else
+            ok("gateway.binding.list", { machineId, ...result }, { machineId });
+        return true;
+    }
+    if (action === "binding" && positional[0] === "clear") {
+        const gatewayId = requirePositional(positional[1], "gatewayId");
+        const result = await client.clearGatewayBinding(machineId, gatewayId, {
+            ...(stringFlag(flags, "chat-id") ? { chatId: stringFlag(flags, "chat-id") } : {}),
+            ...(stringFlag(flags, "thread-id") ? { threadId: stringFlag(flags, "thread-id") } : {}),
+            ...(stringFlag(flags, "session") ? { sessionId: stringFlag(flags, "session") } : {}),
+        });
+        if (!wantsJson(flags))
+            console.log(`Cleared ${result.removedBindings} binding(s) and ${result.removedQueuedInbound} queued message(s) on Daemon ${machineId}.`);
+        else
+            ok("gateway.binding.clear", { machineId, ...result }, { machineId });
+        return true;
+    }
+    if (action === "source" && positional[0] === "inspect") {
+        const gatewayId = requirePositional(positional[1], "gatewayId");
+        const result = await client.inspectGatewaySource(machineId, gatewayId, { verifyCandidate: true });
+        if (!wantsJson(flags)) {
+            console.log(`Gateway ${gatewayId} source: ${result.status}`);
+            console.log(`state digest: ${result.stateDigest}`);
+        }
+        else
+            ok("gateway.source.inspect", { machineId, ...result }, { machineId });
+        return true;
+    }
+    if (action === "store" && positional[0] === "inspect") {
+        const result = await client.inspectGatewayStore(machineId);
+        if (!wantsJson(flags)) {
+            console.log(`Gateway store on Daemon ${machineId}: ${result.repairRequired ? "repair required" : "healthy"}`);
+            console.log(`artifact digest: ${result.artifactDigest}`);
+        }
+        else
+            ok("gateway.store.inspect", { machineId, ...result }, { machineId });
+        return true;
+    }
+    throw new CliError("This Gateway maintenance action is local-only. Remove --machine and run it on the owning Daemon, or use a supported encrypted management action.", "GATEWAY_REMOTE_ACTION_UNSUPPORTED");
+}
+function printRemoteGateway(gateway, verbose = false) {
+    console.log(`${gateway.id}  ${gateway.enabled ? "enabled" : "disabled"}  ${gateway.platform}  ${gateway.runtimeState}`);
+    if (!verbose)
+        return;
+    console.log(`secret: ${gateway.hasSecret ? "set" : "missing"}`);
+    console.log(`inbound: ${gateway.inboundMode}`);
+    console.log(`default: ${gateway.defaultAgent} ${gateway.defaultCwd}`);
+    console.log(`permission: ${gateway.permissionMode ?? "approve-all"}`);
+    console.log(`identities: ${gateway.identities.length}`);
+    console.log(`bindings: ${gateway.counts.bindings}  queued: ${gateway.counts.queue}`);
+}
 async function readGatewayStore() {
     return await readGatewayStoreFile(gatewayConfigPath);
 }
@@ -796,6 +1009,7 @@ function applyGatewayConfigFlags(gateway, flags) {
         defaultAgent: stringFlag(flags, "default-agent") ?? stringFlag(flags, "agent") ?? gateway.defaultAgent,
         defaultCwd: stringFlag(flags, "default-cwd") ?? stringFlag(flags, "cwd") ?? gateway.defaultCwd,
         allowAllUsers: allowAllUsersFlag(flags, gateway.allowAllUsers === true),
+        permissionMode: permissionModeFlag(flags, gateway.permissionMode ?? "approve-all"),
         updatedAt: Date.now(),
     };
     const defaultChatId = stringFlag(flags, "default-chat-id");
@@ -852,6 +1066,7 @@ function publicGateway(gateway) {
             emojiType: gateway.processingReaction.emojiType,
         },
         allowAllUsers: gateway.allowAllUsers === true,
+        permissionMode: gateway.permissionMode ?? "approve-all",
         ...(gateway.sourceNamespaceVersion === 1 ? { sourceNamespaceVersion: 1 } : {}),
         ...(gateway.appId ? { appId: gateway.appId } : {}),
         ...(gateway.domain ? { domain: gateway.domain } : {}),
@@ -936,6 +1151,14 @@ function inboundModeFlag(flags, fallback) {
     }
     return aliases[0] ?? fallback;
 }
+function permissionModeFlag(flags, fallback) {
+    const value = flags["permission-mode"];
+    if (value === undefined || value === false)
+        return fallback;
+    if (value === "approve-all" || value === "approve-reads" || value === "deny-all")
+        return value;
+    throw new CliError("Invalid --permission-mode <approve-all|approve-reads|deny-all>", "INVALID_ARGUMENT");
+}
 function processingReactionFromFlags(flags, fallback) {
     if (flags["reaction-enabled"] === true && flags["reaction-disabled"] === true) {
         throw new CliError("Use only one of --reaction-enabled or --reaction-disabled", "INVALID_ARGUMENT");