@cydm/happy-elves 0.1.0-beta.270 → 0.1.0-beta.271

package/apps/cli/dist/commands/lib/args.js

@@ -32,6 +32,7 @@ const valueFlags = new Set([
     "memory-project",
     "memory-top-n",
     "name",
+    "package-url",
     "model",
     "mode",
     "output",
@@ -61,6 +62,7 @@ const valueFlags = new Set([
     "sessions",
     "session",
     "secret",
+    "sha256",
     "since",
     "source",
     "stop-on",
@@ -81,6 +83,8 @@ const valueFlags = new Set([
     "url",
     "turn",
     "until",
+    "version",
+    "wait-timeout",
 ]);
 const booleanFlags = new Set([
     "all",

package/apps/cli/dist/commands/lib/usage.js

@@ -30,6 +30,10 @@ Check local controller config, relay reachability, and daemon state.
   happy-elves remote add-controller [--device-id <id>] [--device-name <name>] --json
   happy-elves remote rename <deviceId> --name <name> --json
   happy-elves remote revoke <deviceId> --json
+  happy-elves remote daemon-status <machineId> [--json]
+  happy-elves remote daemon-restart <machineId> [--wait] [--timeout 2m] [--json]
+  happy-elves remote daemon-update <machineId> [--version latest|0.1.0-beta.N] [--package-url <url> --sha256 <hex>] [--wait] [--timeout 10m] [--json]
+  happy-elves remote daemon-logs <machineId> [--tail 100] [--json]
 `,
     machine: `Usage:
   happy-elves machine list [--verbose] [--json]

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

@@ -1,5 +1,5 @@
 import os from "node:os";
-import { ControllerClient, configPath, ok, parseControllerJoinUrl, parseDurationMs, randomId, readConfig, relayHealth, requirePositional, requireRelayUrl, requireString, showMachine, wantsJson, wantsVerbose, writeConfig } from "./lib/index.js";
+import { CliError, ControllerClient, configPath, ok, parseControllerJoinUrl, parseDurationMs, randomId, readConfig, relayHealth, requirePositional, requireRelayUrl, requireString, showMachine, wantsJson, wantsVerbose, writeConfig } from "./lib/index.js";
 export async function handleRemote({ domain, action, positional, flags }) {
     if (domain === "remote" && action === "devices") {
         const config = await readConfig(flags);
@@ -81,6 +81,56 @@ export async function handleRemote({ domain, action, positional, flags }) {
         ok("remote.status", data);
         return true;
     }
+    if (domain === "remote" && action === "daemon-status") {
+        const config = await readConfig(flags);
+        const machineId = requirePositional(positional[0], "machineId");
+        const result = await new ControllerClient(config).daemonLifecycle({
+            machineId,
+            action: "status",
+            waitTimeoutMs: parseDurationMs(flags["wait-timeout"], 45_000),
+        });
+        printDaemonLifecycle("remote.daemon-status", result, flags);
+        return true;
+    }
+    if (domain === "remote" && action === "daemon-logs") {
+        const config = await readConfig(flags);
+        const machineId = requirePositional(positional[0], "machineId");
+        const tail = typeof flags.tail === "string" ? Number(flags.tail) : 100;
+        if (!Number.isInteger(tail) || tail <= 0)
+            throw new CliError("--tail must be a positive integer", "INVALID_ARGUMENT");
+        const result = await new ControllerClient(config).daemonLifecycle({
+            machineId,
+            action: "logs",
+            tail,
+            waitTimeoutMs: parseDurationMs(flags["wait-timeout"], 45_000),
+        });
+        printDaemonLifecycle("remote.daemon-logs", result, flags);
+        return true;
+    }
+    if (domain === "remote" && (action === "daemon-restart" || action === "daemon-update")) {
+        const config = await readConfig(flags);
+        const client = new ControllerClient(config);
+        const machineId = requirePositional(positional[0], "machineId");
+        const isUpdate = action === "daemon-update";
+        const result = await client.daemonLifecycle({
+            machineId,
+            action: isUpdate ? "update" : "restart",
+            targetVersion: isUpdate ? (typeof flags.version === "string" ? flags.version : "latest") : undefined,
+            packageUrl: isUpdate && typeof flags["package-url"] === "string" ? flags["package-url"] : undefined,
+            sha256: isUpdate && typeof flags.sha256 === "string" ? flags.sha256 : undefined,
+            waitTimeoutMs: parseDurationMs(flags["wait-timeout"], 45_000),
+        });
+        let finalResult = result;
+        if (result.accepted === true && flags.wait) {
+            finalResult = await waitForDaemonLifecycle(client, machineId, result.requestId, isUpdate ? "update" : "restart", {
+                timeoutMs: parseDurationMs(flags.timeout, isUpdate ? 10 * 60_000 : 2 * 60_000),
+            });
+        }
+        printDaemonLifecycle(isUpdate ? "remote.daemon-update" : "remote.daemon-restart", finalResult, flags);
+        if (finalResult.accepted === false || finalResult.updateState?.status === "failed")
+            process.exitCode = 1;
+        return true;
+    }
     if (domain === "remote" &&
         ((action === "pairing" && positional[0] === "new") || (action === "machine-pairing" && positional[0] === "new"))) {
         const config = await readConfig(flags);
@@ -148,4 +198,83 @@ export async function handleRemote({ domain, action, positional, flags }) {
     }
     return false;
 }
+function printDaemonLifecycle(type, result, flags) {
+    const success = result.accepted !== false && result.updateState?.status !== "failed";
+    if (wantsJson(flags)) {
+        ok(type, result, { requestId: result.requestId, machineId: result.machineId }, success);
+        return;
+    }
+    const state = result.updateState;
+    const summary = [
+        `Machine: ${result.machineId}`,
+        `Action: ${result.action}`,
+        `Version: ${result.version ?? "-"}`,
+        `Running: ${result.running === undefined ? "-" : result.running ? "yes" : "no"}`,
+        `Install: ${result.installMode ?? "-"}`,
+    ];
+    if (result.updateSupported === false)
+        summary.push(`Update: unsupported (${result.updateUnsupportedReason ?? "unknown"})`);
+    if (result.accepted !== undefined)
+        summary.push(`Accepted: ${result.accepted ? "yes" : "no"}`);
+    if (state) {
+        summary.push(`Update state: ${state.status}`);
+        if (state.targetVersion)
+            summary.push(`Target: ${state.targetVersion}`);
+        if (state.toVersion)
+            summary.push(`Installed: ${state.toVersion}`);
+        if (state.logPath)
+            summary.push(`Log: ${state.logPath}`);
+        if (state.error)
+            summary.push(`Error: ${state.error}`);
+    }
+    for (const line of summary)
+        console.log(line);
+    if (result.logs?.length) {
+        console.log("Logs:");
+        for (const line of result.logs)
+            console.log(line);
+    }
+}
+async function waitForDaemonLifecycle(client, machineId, requestId, action, options) {
+    const deadline = Date.now() + Math.max(1, options.timeoutMs);
+    let lastResult;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            const result = await client.daemonLifecycle({ machineId, action: "status", waitTimeoutMs: 15_000 });
+            lastResult = result;
+            const state = result.updateState;
+            if (state?.requestId === requestId) {
+                if (state.status === "succeeded" || state.status === "failed")
+                    return result;
+            }
+            else if (action === "restart" && result.running === true) {
+                return result;
+            }
+        }
+        catch (error) {
+            lastError = error;
+            const code = errorCode(error);
+            if (code !== "MACHINE_OFFLINE" && code !== "COMMAND_TIMEOUT" && code !== "RELAY_CONNECT_TIMEOUT")
+                throw error;
+        }
+        await sleep(1000);
+    }
+    if (lastResult)
+        return {
+            ...lastResult,
+            accepted: false,
+            updateUnsupportedReason: `WAIT_TIMEOUT_${requestId}`,
+        };
+    throw new CliError(`Timed out waiting for daemon ${action}: ${errorMessage(lastError)}`, "COMMAND_TIMEOUT");
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error ? String(error.code) : undefined;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error ?? "unknown");
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 //# sourceMappingURL=remote.js.map

package/apps/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cydm/happy-elves-cli",
-  "version": "0.1.0-beta.270",
+  "version": "0.1.0-beta.271",
   "private": true,
   "type": "module"
 }

package/apps/daemon/dist/paths.d.ts

@@ -8,6 +8,8 @@ export declare const loopStoreLockPath: string;
 export declare const gatewayStorePath: string;
 export declare const scheduleStorePath: string;
 export declare const memoryRootDir: string;
+export declare const updatesDir: string;
+export declare const updateStatePath: string;
 export declare const pidPath: string;
 export declare const daemonScriptPath: string;
 export declare const daemonScriptRelativePath: string;

package/apps/daemon/dist/paths.js

@@ -13,6 +13,8 @@ export const loopStoreLockPath = path.join(configDir, "loops.json.lock");
 export const gatewayStorePath = path.join(configDir, "gateway.json");
 export const scheduleStorePath = path.join(configDir, "schedules.json");
 export const memoryRootDir = path.join(configDir, "memory");
+export const updatesDir = path.join(configDir, "updates");
+export const updateStatePath = path.join(configDir, "update-state.json");
 export const pidPath = path.join(configDir, "daemon.pid");
 export const daemonScriptPath = fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "./cli.ts" : "./cli.js", import.meta.url));
 export const daemonScriptRelativePath = path.relative(process.cwd(), daemonScriptPath);

package/apps/daemon/dist/relay/connection.js

@@ -12,6 +12,7 @@ import { handleFork, handleRename, handleRewind } from "../session/primitives.js
 import { handleReconcileTurn } from "../session/reconcile.js";
 import { parseRelayMessage, relayWsUrl } from "../relay-http.js";
 import { handleDevExec, handleDiagnose } from "./devtools.js";
+import { handleDaemonLifecycleCommand } from "./lifecycle.js";
 import { registerMachine } from "./register.js";
 import { clearActiveRelaySocket, configureRelaySender, flushRelayOutbox, handleMachineMessageAck, send, sendCommandResponse, setActiveRelaySocket, } from "./send.js";
 async function handleServerMessage(ws, config, message) {
@@ -63,6 +64,10 @@ async function handleServerMessage(ws, config, message) {
         await handleDevExec(ws, config, message);
         return;
     }
+    if (message.type === "machine:daemonLifecycle") {
+        await handleDaemonLifecycleCommand(ws, config, message);
+        return;
+    }
     if (message.type === "machine:gateway") {
         await handleGatewayCommand(ws, config, message);
         return;

package/apps/daemon/dist/relay/lifecycle.d.ts

@@ -0,0 +1,7 @@
+import type { MachineCommand } from "../../../../packages/shared/dist/index.js";
+import type { DaemonConfig } from "../types.js";
+type DaemonLifecycleCommand = Extract<MachineCommand, {
+    type: "machine:daemonLifecycle";
+}>;
+export declare function handleDaemonLifecycleCommand(ws: WebSocket, config: DaemonConfig, command: DaemonLifecycleCommand): Promise<void>;
+export {};

package/apps/daemon/dist/relay/lifecycle.js

@@ -0,0 +1,476 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import daemonPackage from "../../package.json" with { type: "json" };
+import { appendAudit } from "../audit.js";
+import { auditLogPath, configDir, daemonScriptPath, pidPath, updateStatePath, updatesDir } from "../paths.js";
+import { localStatus } from "../process.js";
+import { claimCommandRequest, sendCommandResponse } from "./send.js";
+const defaultTargetPackage = "@cydm/happy-elves";
+const maxLogTail = 2000;
+export async function handleDaemonLifecycleCommand(ws, config, command) {
+    if (!claimCommandRequest(ws, command.requestId))
+        return;
+    const result = await executeDaemonLifecycleCommand(command);
+    await appendAudit({
+        machineId: config.machineId,
+        actor: "user",
+        action: `daemon.lifecycle.${command.action}`,
+        summary: `Daemon lifecycle ${command.action}: ${result.accepted === false ? "rejected" : "accepted"}`,
+        evidence: {
+            requestId: command.requestId,
+            targetVersion: command.targetVersion,
+            packageUrl: command.packageUrl ? redactUrl(command.packageUrl) : undefined,
+            status: result.updateState?.status,
+            updateSupported: result.updateSupported,
+            updateUnsupportedReason: result.updateUnsupportedReason,
+        },
+    });
+    await sendCommandResponse(ws, {
+        type: "machine:daemonLifecycleResult",
+        requestId: command.requestId,
+        machineId: config.machineId,
+        result,
+    });
+    if ((command.action === "restart" || command.action === "update") && result.accepted === true && result.updateState) {
+        spawnUpdaterRunner(result.updateState.requestId);
+    }
+}
+async function executeDaemonLifecycleCommand(command) {
+    if (command.action === "status") {
+        return await lifecycleStatus("status");
+    }
+    if (command.action === "logs") {
+        return {
+            ...(await lifecycleStatus("logs")),
+            logs: await readLifecycleLogTail(command.tail ?? 100),
+        };
+    }
+    if (command.action === "restart") {
+        const state = await createUpdateIntent(command, "restart");
+        await writeUpdateState(state);
+        await writeRunnerFile(state.requestId, runnerInput(state, "restart"));
+        return {
+            ...(await lifecycleStatus("restart")),
+            accepted: true,
+            updateState: state,
+        };
+    }
+    if (command.action === "update") {
+        const status = await lifecycleStatus("update");
+        if (!status.updateSupported) {
+            return {
+                ...status,
+                accepted: false,
+                updateUnsupportedReason: status.updateUnsupportedReason ?? "UPDATE_UNSUPPORTED_INSTALL_MODE",
+            };
+        }
+        if (command.packageUrl && !command.sha256) {
+            return {
+                ...status,
+                accepted: false,
+                updateUnsupportedReason: "PACKAGE_SHA256_REQUIRED",
+            };
+        }
+        if (command.sha256 && !command.packageUrl) {
+            return {
+                ...status,
+                accepted: false,
+                updateUnsupportedReason: "PACKAGE_URL_REQUIRED_FOR_SHA256",
+            };
+        }
+        const state = await createUpdateIntent(command, "update");
+        await writeUpdateState(state);
+        await writeRunnerFile(state.requestId, runnerInput(state, "update"));
+        return {
+            ...status,
+            accepted: true,
+            updateState: state,
+        };
+    }
+    return {
+        action: command.action,
+        accepted: false,
+        updateUnsupportedReason: `Unsupported daemon lifecycle action: ${command.action}`,
+    };
+}
+async function lifecycleStatus(action) {
+    const local = await localStatus();
+    const installMode = detectInstallMode();
+    const updateState = await readUpdateState();
+    return {
+        action,
+        version: daemonPackage.version,
+        pid: local.pid,
+        running: local.running,
+        platform: process.platform,
+        arch: process.arch,
+        installMode,
+        updateSupported: installMode === "npm-global",
+        ...(installMode === "npm-global" ? {} : { updateUnsupportedReason: "UPDATE_UNSUPPORTED_DEV_INSTALL" }),
+        ...(updateState ? { updateState } : {}),
+    };
+}
+function detectInstallMode() {
+    if (process.env.HAPPY_ELVES_TEST_INSTALL_MODE === "npm-global")
+        return "npm-global";
+    if (process.env.HAPPY_ELVES_TEST_INSTALL_MODE === "repo-dev")
+        return "repo-dev";
+    if (daemonPackage.name === "@cydm/happy-elves-daemon")
+        return "npm-global";
+    if (daemonPackage.private === true)
+        return "repo-dev";
+    return "unknown";
+}
+async function createUpdateIntent(command, action) {
+    const logPath = path.join(updatesDir, command.requestId, "updater.log");
+    const targetVersion = action === "update" ? (command.targetVersion ?? "latest") : undefined;
+    const packageSpec = action === "update" && !command.packageUrl ? `${defaultTargetPackage}@${targetVersion}` : undefined;
+    return {
+        requestId: command.requestId,
+        action,
+        ...(targetVersion ? { targetVersion } : {}),
+        ...(packageSpec ? { packageSpec } : {}),
+        ...(command.packageUrl ? { packageUrl: command.packageUrl } : {}),
+        ...(command.sha256 ? { sha256: command.sha256 } : {}),
+        status: "accepted",
+        fromVersion: daemonPackage.version,
+        startedAt: new Date().toISOString(),
+        logPath,
+    };
+}
+async function readUpdateState() {
+    try {
+        return JSON.parse(await fs.readFile(updateStatePath, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        return undefined;
+    }
+}
+async function writeUpdateState(state) {
+    await fs.mkdir(path.dirname(updateStatePath), { recursive: true });
+    const tempPath = `${updateStatePath}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(tempPath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    await fs.rename(tempPath, updateStatePath);
+}
+function runnerInput(state, action) {
+    return {
+        action,
+        configDir,
+        daemonScriptPath,
+        homeEnv: process.env.HAPPY_ELVES_HOME ?? configDir,
+        logPath: state.logPath,
+        packageSpec: state.packageSpec,
+        packageUrl: state.packageUrl,
+        pidPath,
+        requestId: state.requestId,
+        sha256: state.sha256,
+        startMode: action === "restart" ? "current-script" : "global-cli",
+        statePath: updateStatePath,
+        targetPackage: defaultTargetPackage,
+        targetVersion: state.targetVersion,
+    };
+}
+async function writeRunnerFile(requestId, input) {
+    const runnerDir = path.join(updatesDir, requestId);
+    await fs.mkdir(runnerDir, { recursive: true });
+    await fs.writeFile(path.join(runnerDir, "runner.mjs"), renderRunnerScript(input), { mode: 0o700 });
+}
+function spawnUpdaterRunner(requestId) {
+    if (process.env.HAPPY_ELVES_TEST_NO_SPAWN_UPDATER === "1")
+        return;
+    const runnerPath = path.join(updatesDir, requestId, "runner.mjs");
+    const child = spawn(process.execPath, [runnerPath], {
+        cwd: process.cwd(),
+        detached: true,
+        env: { ...process.env, HAPPY_ELVES_HOME: process.env.HAPPY_ELVES_HOME ?? configDir },
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    child.unref();
+}
+async function readLifecycleLogTail(tail) {
+    const boundedTail = Math.max(1, Math.min(maxLogTail, Math.floor(tail)));
+    const state = await readUpdateState();
+    const paths = [auditLogPath, state?.logPath].filter((item) => Boolean(item));
+    const lines = [];
+    for (const filePath of paths) {
+        try {
+            const text = await fs.readFile(filePath, "utf8");
+            const label = filePath === auditLogPath ? "daemon" : "updater";
+            for (const line of text.split(/\r?\n/u).filter(Boolean).slice(-boundedTail)) {
+                lines.push(`[${label}] ${line}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                lines.push(`[log-error] ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    return lines.slice(-boundedTail);
+}
+function redactUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.password)
+            url.password = "redacted";
+        if (url.username)
+            url.username = "redacted";
+        return url.toString();
+    }
+    catch {
+        return value;
+    }
+}
+function renderRunnerScript(input) {
+    const runner = {
+        ...input,
+        startDelayMs: 750,
+    };
+    const inputJson = JSON.stringify(runner);
+    return `#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const input = ${inputJson};
+
+main().catch(async (error) => {
+  await fail(error);
+  process.exitCode = 1;
+});
+
+async function main() {
+  await fs.mkdir(path.dirname(input.logPath), { recursive: true });
+  await delay(input.startDelayMs);
+  await updateState({ status: "running" });
+  await log("runner started " + JSON.stringify({ action: input.action, targetVersion: input.targetVersion, packageSpec: input.packageSpec, packageUrl: input.packageUrl ? redactUrl(input.packageUrl) : undefined }));
+  await stopDaemon();
+  if (input.action === "update") {
+    await installPackage();
+  }
+  await startDaemon();
+  await waitForDaemonRunning();
+  const version = await currentHappyElvesVersion().catch(() => undefined);
+  await updateState({ status: "succeeded", finishedAt: new Date().toISOString(), ...(version ? { toVersion: version } : {}) });
+  await log("runner succeeded");
+}
+
+async function fail(error) {
+  const message = error instanceof Error ? error.stack || error.message : String(error);
+  await log("runner failed: " + message).catch(() => {});
+  await updateState({ status: "failed", finishedAt: new Date().toISOString(), error: String(error instanceof Error ? error.message : error) }).catch(() => {});
+}
+
+async function updateState(patch) {
+  const current = JSON.parse(await fs.readFile(input.statePath, "utf8"));
+  const next = { ...current, ...patch };
+  const tempPath = input.statePath + "." + process.pid + "." + Date.now() + ".tmp";
+  await fs.writeFile(tempPath, JSON.stringify(next, null, 2) + "\\n", { mode: 0o600 });
+  await fs.rename(tempPath, input.statePath);
+}
+
+async function log(line) {
+  await fs.mkdir(path.dirname(input.logPath), { recursive: true });
+  await fs.appendFile(input.logPath, "[" + new Date().toISOString() + "] " + line + "\\n", { mode: 0o600 });
+}
+
+async function stopDaemon() {
+  await updateState({ status: "stopping" });
+  const pid = await readPid();
+  if (!pid || pid === process.pid) {
+    await fs.rm(input.pidPath, { force: true }).catch(() => {});
+    await log("no managed daemon pid to stop");
+    return;
+  }
+  await log("stopping daemon pid " + pid);
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (error) {
+    await log("SIGTERM failed: " + String(error instanceof Error ? error.message : error));
+  }
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(pid)) {
+      await fs.rm(input.pidPath, { force: true }).catch(() => {});
+      await log("daemon stopped");
+      return;
+    }
+    await delay(200);
+  }
+  throw new Error("Timed out stopping daemon pid " + pid);
+}
+
+async function installPackage() {
+  await updateState({ status: "installing" });
+  if (input.packageUrl) {
+    const tarballPath = path.join(path.dirname(input.logPath), "package.tgz");
+    await download(input.packageUrl, tarballPath);
+    if (!input.sha256) throw new Error("packageUrl update requires sha256");
+    const actual = await sha256File(tarballPath);
+    if (actual.toLowerCase() !== String(input.sha256).toLowerCase()) {
+      throw new Error("Package sha256 mismatch: expected " + input.sha256 + " got " + actual);
+    }
+    await run(commandName("npm"), ["install", "-g", "--force", tarballPath], { timeoutMs: 300_000 });
+    return;
+  }
+  const spec = input.packageSpec || input.targetPackage + "@" + (input.targetVersion || "latest");
+  await run(commandName("npm"), ["install", "-g", "--force", spec], { timeoutMs: 300_000 });
+}
+
+async function startDaemon() {
+  await updateState({ status: "starting" });
+  if (input.startMode === "current-script") {
+    await log("starting daemon from current script");
+    await spawnDetached(process.execPath, [input.daemonScriptPath, "start", "--json"]);
+    return;
+  }
+  await log("starting daemon from global happy-elves");
+  await spawnDetached(commandName("happy-elves"), ["daemon", "start", "--json"]);
+}
+
+async function waitForDaemonRunning() {
+  const deadline = Date.now() + 45_000;
+  while (Date.now() < deadline) {
+    const result = await captureStatus().catch(() => undefined);
+    if (result?.ok === true && (result.data?.local?.running === true || result.data?.running === true)) {
+      await log("daemon status running");
+      return;
+    }
+    await delay(1000);
+  }
+  throw new Error("Timed out waiting for restarted daemon");
+}
+
+async function captureStatus() {
+  const status = statusCommand();
+  const result = await run(status.command, status.args, { timeoutMs: 10_000, allowFailure: true });
+  const text = result.stdout.trim();
+  return text ? JSON.parse(text) : undefined;
+}
+
+async function currentHappyElvesVersion() {
+  if (input.startMode === "current-script") return undefined;
+  const result = await run(commandName("happy-elves"), ["--version"], { timeoutMs: 10_000, allowFailure: true });
+  const text = (result.stdout + "\\n" + result.stderr).trim();
+  const match = text.match(/(\\d+\\.\\d+\\.\\d+(?:-[\\w.-]+)?)/);
+  return match?.[1];
+}
+
+function statusCommand() {
+  if (input.startMode === "current-script") {
+    return { command: process.execPath, args: [input.daemonScriptPath, "status", "--json"] };
+  }
+  return { command: commandName("happy-elves"), args: ["daemon", "status", "--local", "--json"] };
+}
+
+async function spawnDetached(command, args) {
+  const child = spawn(command, args, {
+    cwd: input.configDir,
+    detached: true,
+    env: { ...process.env, HAPPY_ELVES_HOME: input.homeEnv },
+    stdio: "ignore",
+    windowsHide: true,
+  });
+  child.unref();
+  await log("spawned " + command + " pid " + (child.pid || "unknown"));
+}
+
+async function run(command, args, options = {}) {
+  await log("run " + command + " " + args.join(" "));
+  return await new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: input.configDir,
+      env: { ...process.env, HAPPY_ELVES_HOME: input.homeEnv },
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error("Command timed out: " + command));
+    }, options.timeoutMs || 60_000);
+    child.stdout?.on("data", (chunk) => { stdout += chunk.toString(); });
+    child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      const compactStdout = compact(stdout);
+      const compactStderr = compact(stderr);
+      if (compactStdout) void log("stdout: " + compactStdout).catch(() => {});
+      if (compactStderr) void log("stderr: " + compactStderr).catch(() => {});
+      if (!options.allowFailure && code !== 0) {
+        reject(new Error(command + " exited " + (code ?? signal ?? "unknown") + ": " + compactStderr));
+        return;
+      }
+      resolve({ code, signal, stdout, stderr });
+    });
+  });
+}
+
+async function download(url, targetPath) {
+  await log("download " + redactUrl(url));
+  const response = await fetch(url);
+  if (!response.ok) throw new Error("Download failed: HTTP " + response.status);
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await fs.writeFile(targetPath, buffer, { mode: 0o600 });
+}
+
+async function sha256File(filePath) {
+  const hash = createHash("sha256");
+  hash.update(await fs.readFile(filePath));
+  return hash.digest("hex");
+}
+
+async function readPid() {
+  try {
+    const raw = await fs.readFile(input.pidPath, "utf8");
+    const pid = Number(raw.trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+  } catch (error) {
+    if (error && error.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function commandName(name) {
+  return process.platform === "win32" ? name + ".cmd" : name;
+}
+
+function compact(text) {
+  return text.replace(/\\s+/g, " ").trim().slice(0, 2000);
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function redactUrl(value) {
+  try {
+    const url = new URL(value);
+    if (url.username) url.username = "redacted";
+    if (url.password) url.password = "redacted";
+    return url.toString();
+  } catch {
+    return value;
+  }
+}
+`;
+}
+//# sourceMappingURL=lifecycle.js.map

package/apps/daemon/dist/relay/register.js

@@ -57,6 +57,7 @@ export async function registerMachine(ws, config) {
             directoryBrowser: true,
             filePreview: true,
             devTools: process.env.HAPPY_ELVES_DEV_REMOTE_EXEC === "1",
+            daemonLifecycle: true,
         },
     });
 }

package/apps/daemon/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cydm/happy-elves-daemon",
-  "version": "0.1.0-beta.270",
+  "version": "0.1.0-beta.271",
   "private": true,
   "type": "module"
 }

package/apps/relay/dist/controller-handlers.js

@@ -483,6 +483,39 @@ export function handleControllerMessage(context, connection, message) {
         });
         return;
     }
+    if (message.type === "controller:daemonLifecycle") {
+        if (!allowControllerAction(connection, "machine.lifecycle", message.requestId))
+            return;
+        if (!allowControllerMachine(connection, message.machineId, message.requestId))
+            return;
+        const machineConnection = connectedMachine(connection.accountId, message.machineId);
+        if (!machineConnection) {
+            sendMachineOffline(connection, message.requestId);
+            return;
+        }
+        if (machineCapabilities(connection.accountId, message.machineId)?.daemonLifecycle !== true) {
+            sendError(connection, {
+                type: "server:error",
+                requestId: message.requestId,
+                code: "DAEMON_LIFECYCLE_UNSUPPORTED",
+                capability: "machine.lifecycle",
+                message: "This daemon does not support remote lifecycle commands. Upgrade it manually once.",
+            });
+            return;
+        }
+        markCommandPending(connection.accountId, message.machineId, message.requestId, { command: "daemonLifecycle" });
+        send(machineConnection.socket, {
+            type: "machine:daemonLifecycle",
+            requestId: message.requestId,
+            machineId: message.machineId,
+            action: message.action,
+            targetVersion: message.targetVersion,
+            packageUrl: message.packageUrl,
+            sha256: message.sha256,
+            tail: message.tail,
+        });
+        return;
+    }
     if (message.type === "controller:gateway") {
         if (!allowControllerAction(connection, "gateway.manage", message.requestId))
             return;

package/apps/relay/dist/machine-handlers.js

@@ -119,6 +119,18 @@ export function handleMachineMessage(context, connection, message) {
         broadcastControllers(connection.accountId, response);
         return;
     }
+    if (message.type === "machine:daemonLifecycleResult") {
+        const response = {
+            type: "server:daemonLifecycleResult",
+            requestId: message.requestId,
+            machineId: connection.machineId,
+            result: message.result,
+        };
+        rememberCommandResponse(connection.accountId, message.requestId, response);
+        clearCommandPending(connection.accountId, message.requestId);
+        broadcastControllers(connection.accountId, response);
+        return;
+    }
     if (message.type === "machine:gatewayResult") {
         const response = {
             type: "server:gatewayResult",

package/apps/relay/dist/projections.js

@@ -114,6 +114,8 @@ export function normalizeMachineCapabilities(value) {
         capabilities.filePreview = record.filePreview;
     if (typeof record.devTools === "boolean")
         capabilities.devTools = record.devTools;
+    if (typeof record.daemonLifecycle === "boolean")
+        capabilities.daemonLifecycle = record.daemonLifecycle;
     if (isRecord(record.sessionPrimitives)) {
         capabilities.sessionPrimitives = {
             resume: primitiveSupport(record.sessionPrimitives.resume),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cydm/happy-elves",
-  "version": "0.1.0-beta.270",
+  "version": "0.1.0-beta.271",
   "description": "Remote controller for local coding agents with hosted or self-hosted relay support.",
   "type": "module",
   "bin": {

package/packages/client/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { type DirectoryListing, type EncryptedSessionEvent, type EncryptedEnvelope, type HistoricalSessionSnapshot, type MachineSnapshot, type PairingStartResponse, type SessionSnapshot } from "../../shared/dist/index.js";
 import { sendCommand } from "./transport.js";
-import type { AddControllerDeviceInput, AddControllerDeviceResult, CancelInput, CollectInput, CommandResult, ControllerClientConfig, ControllerInviteClaimInput, ControllerInviteClaimResult, ControllerInviteCreateInput, ControllerInviteCreateResult, ControllerSnapshot, ControllerSubscriptionHandlers, CreateScopedTokenInput, CreateSessionInput, DecodedSessionEvent, DecodedSessionEventsPage, DeviceListResponse, DirectoryInput, FilePreviewInput, ForkInput, GatewayCommandInput, GatewayCommandResponse, HistoricalSessionListPage, HistoricalSessionsInput, ImportHistoricalSessionInput, MachineMetadata, MachineDevExecInput, MachineDevExecResponse, MachineDiagnosticsResponse, MemoryCommandInput, MemoryCommandResponse, DecodedMemoryRecord, RepairSessionHeadInput, RepairSessionHeadResult, RunOptions, ScheduleCommandInput, ScheduleCommandResponse, ScopedTokenInfo, ScopedTokenSelf, SessionFilter, SessionMetadata, WaitInput, MemorySaveInput, MemorySearchInput, MemorySettings, TurnReconcileResponse, WorkspaceCwdPin, WorkspaceCwdPinInput, WorkspaceProjectPreference, WorkspaceProjectPreferenceInput, WorkspaceRecentSession, WorkspaceSessionStarResult, WorkspaceSyncState } from "./types.js";
+import type { AddControllerDeviceInput, AddControllerDeviceResult, CancelInput, CollectInput, CommandResult, ControllerClientConfig, ControllerInviteClaimInput, ControllerInviteClaimResult, ControllerInviteCreateInput, ControllerInviteCreateResult, ControllerSnapshot, ControllerSubscriptionHandlers, CreateScopedTokenInput, CreateSessionInput, DaemonLifecycleInput, DaemonLifecycleResponse, DecodedSessionEvent, DecodedSessionEventsPage, DeviceListResponse, DirectoryInput, FilePreviewInput, ForkInput, GatewayCommandInput, GatewayCommandResponse, HistoricalSessionListPage, HistoricalSessionsInput, ImportHistoricalSessionInput, MachineMetadata, MachineDevExecInput, MachineDevExecResponse, MachineDiagnosticsResponse, MemoryCommandInput, MemoryCommandResponse, DecodedMemoryRecord, RepairSessionHeadInput, RepairSessionHeadResult, RunOptions, ScheduleCommandInput, ScheduleCommandResponse, ScopedTokenInfo, ScopedTokenSelf, SessionFilter, SessionMetadata, WaitInput, MemorySaveInput, MemorySearchInput, MemorySettings, TurnReconcileResponse, WorkspaceCwdPin, WorkspaceCwdPinInput, WorkspaceProjectPreference, WorkspaceProjectPreferenceInput, WorkspaceRecentSession, WorkspaceSessionStarResult, WorkspaceSyncState } from "./types.js";
 export declare class ControllerClient {
     readonly config: ControllerClientConfig;
     constructor(config: ControllerClientConfig);
@@ -73,6 +73,7 @@ export declare class ControllerClient {
     previewFile(input: FilePreviewInput): Promise<import("../../shared/dist/index.js").FilePreviewResult>;
     machineDiagnostics(machineId: string): Promise<MachineDiagnosticsResponse>;
     machineDevExec(input: MachineDevExecInput): Promise<MachineDevExecResponse>;
+    daemonLifecycle(input: DaemonLifecycleInput): Promise<DaemonLifecycleResponse>;
     gateway(input: GatewayCommandInput): Promise<GatewayCommandResponse>;
     schedule(input: ScheduleCommandInput): Promise<ScheduleCommandResponse>;
     memory(input: MemoryCommandInput): Promise<MemoryCommandResponse>;

package/packages/client/dist/client.js

@@ -3,7 +3,7 @@ import { addControllerDevice, claimControllerInvite, createControllerInvite, cre
 import { ControllerClientError, ControllerCommandError } from "./errors.js";
 import { authenticatedJson, normalizeRelayUrl, readRelayJson, relayHttpError } from "./http.js";
 import { parseRepairSessionHeadResult, parseSessionEventsResponse, } from "./parsers.js";
-import { sendAndWaitForDirectoryListing, sendAndWaitForFilePreview, sendAndWaitForGatewayResult, sendAndWaitForHistoricalSessions, sendAndWaitForMachineDevExecResult, sendAndWaitForMachineDiagnostics, sendAndWaitForMemoryResult, sendAndWaitForScheduleResult, sendAndWaitForTurnReconcileResult, sendCommand, subscribe, } from "./transport.js";
+import { sendAndWaitForDirectoryListing, sendAndWaitForDaemonLifecycleResult, sendAndWaitForFilePreview, sendAndWaitForGatewayResult, sendAndWaitForHistoricalSessions, sendAndWaitForMachineDevExecResult, sendAndWaitForMachineDiagnostics, sendAndWaitForMemoryResult, sendAndWaitForScheduleResult, sendAndWaitForTurnReconcileResult, sendCommand, subscribe, } from "./transport.js";
 import { DEFAULT_SESSION_CREATE_WAIT_MS, } from "./types.js";
 import { isWaitCondition, matchesWaitCondition, parseEventCursor, parseEventLimit, parsePositiveDuration, requireNonEmpty, sleep, } from "./validation.js";
 const DEFAULT_BLOCKING_RUN_WAIT_MS = 30 * 60 * 1000;
@@ -364,6 +364,21 @@ export class ControllerClient {
         }, input.waitTimeoutMs);
         return message.result;
     }
+    async daemonLifecycle(input) {
+        const machineId = requireNonEmpty(input.machineId, "machineId");
+        const requestId = randomId("req");
+        const message = await sendAndWaitForDaemonLifecycleResult(this.config, {
+            type: "controller:daemonLifecycle",
+            requestId,
+            machineId,
+            action: input.action,
+            targetVersion: input.targetVersion,
+            packageUrl: input.packageUrl,
+            sha256: input.sha256,
+            tail: input.tail,
+        }, input.waitTimeoutMs);
+        return { ...message.result, requestId, machineId: message.machineId };
+    }
     async gateway(input) {
         const machineId = requireNonEmpty(input.machineId, "machineId");
         const requestId = randomId("req");

package/packages/client/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { ControllerClient } from "./client.js";
 export { ControllerClientError, ControllerCommandError } from "./errors.js";
-export type { AddControllerDeviceInput, AddControllerDeviceResult, CancelInput, CollectInput, CommandResult, ControllerClientConfig, ControllerDevice, ControllerInviteClaimInput, ControllerInviteClaimResult, ControllerInviteCreateInput, ControllerInviteCreateResult, ControllerSnapshot, ControllerSubscriptionHandlers, CreateScopedTokenInput, CreateSessionInput, DecodedSessionEvent, DecodedSessionEventsPage, DeviceListResponse, DirectoryInput, DirectoryListResponse, FilePreviewInput, FilePreviewResponse, EventCursor, ForkInput, HistoricalSessionListPage, HistoricalSessionListResponse, HistoricalSessionsInput, ImportHistoricalSessionInput, MachineListResponse, MachineMetadata, DecodedMemoryRecord, EncryptedMemoryRecord, MemoryPayload, MemoryCommandInput, MemoryCommandResponse, MemorySaveInput, MemorySearchInput, MemorySettings, PermissionMode, RepairSessionHeadInput, RepairSessionHeadResult, RunOptions, ScopedTokenInfo, ScopedTokenScope, ScopedTokenSelf, SessionFilter, SessionMetadata, WaitCondition, WaitInput, WorkspaceCwdPin, WorkspaceCwdPinInput, WorkspaceProjectPreference, WorkspaceProjectPreferenceInput, WorkspaceRecentSession, WorkspaceSessionStar, WorkspaceSessionStarResult, WorkspaceSyncState, } from "./types.js";
+export type { AddControllerDeviceInput, AddControllerDeviceResult, CancelInput, CollectInput, CommandResult, ControllerClientConfig, ControllerDevice, ControllerInviteClaimInput, ControllerInviteClaimResult, ControllerInviteCreateInput, ControllerInviteCreateResult, ControllerSnapshot, ControllerSubscriptionHandlers, CreateScopedTokenInput, CreateSessionInput, DecodedSessionEvent, DecodedSessionEventsPage, DaemonLifecycleInput, DaemonLifecycleResponse, DeviceListResponse, DirectoryInput, DirectoryListResponse, FilePreviewInput, FilePreviewResponse, EventCursor, ForkInput, HistoricalSessionListPage, HistoricalSessionListResponse, HistoricalSessionsInput, ImportHistoricalSessionInput, MachineListResponse, MachineMetadata, DecodedMemoryRecord, EncryptedMemoryRecord, MemoryPayload, MemoryCommandInput, MemoryCommandResponse, MemorySaveInput, MemorySearchInput, MemorySettings, PermissionMode, RepairSessionHeadInput, RepairSessionHeadResult, RunOptions, ScopedTokenInfo, ScopedTokenScope, ScopedTokenSelf, SessionFilter, SessionMetadata, WaitCondition, WaitInput, WorkspaceCwdPin, WorkspaceCwdPinInput, WorkspaceProjectPreference, WorkspaceProjectPreferenceInput, WorkspaceRecentSession, WorkspaceSessionStar, WorkspaceSessionStarResult, WorkspaceSyncState, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/packages/client/dist/transport.d.ts

@@ -37,6 +37,11 @@ export declare function sendAndWaitForMachineDevExecResult(config: ControllerCli
 }>, waitTimeoutMs?: number): Promise<Extract<ServerMessage, {
     type: "server:machineDevExecResult";
 }>>;
+export declare function sendAndWaitForDaemonLifecycleResult(config: ControllerClientConfig, command: Extract<ControllerClientMessage, {
+    type: "controller:daemonLifecycle";
+}>, waitTimeoutMs?: number): Promise<Extract<ServerMessage, {
+    type: "server:daemonLifecycleResult";
+}>>;
 export declare function sendAndWaitForGatewayResult(config: ControllerClientConfig, command: Extract<ControllerClientMessage, {
     type: "controller:gateway";
 }>): Promise<Extract<ServerMessage, {

package/packages/client/dist/transport.js

@@ -64,6 +64,10 @@ export function subscribe(config, handlers) {
             void handlers.onMemoryResult?.(message);
             return;
         }
+        if (message.type === "server:daemonLifecycleResult") {
+            void handlers.onDaemonLifecycleResult?.(message);
+            return;
+        }
         if (message.type === "server:turnReconciled") {
             void handlers.onTurnReconciled?.(message);
             return;
@@ -248,6 +252,9 @@ export async function sendAndWaitForMachineDiagnostics(config, command) {
 export async function sendAndWaitForMachineDevExecResult(config, command, waitTimeoutMs) {
     return await sendAndWaitForServerMessage(config, command, "server:machineDevExecResult", "machine dev exec result; remote result is unknown", waitTimeoutMs ?? (command.timeoutMs ?? 60_000) + 15_000);
 }
+export async function sendAndWaitForDaemonLifecycleResult(config, command, waitTimeoutMs) {
+    return await sendAndWaitForServerMessage(config, command, "server:daemonLifecycleResult", "daemon lifecycle result", waitTimeoutMs ?? 45_000);
+}
 export async function sendAndWaitForGatewayResult(config, command) {
     return await sendAndWaitForServerMessage(config, command, "server:gatewayResult", "gateway result", 30_000);
 }

package/packages/client/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { DirectoryListing, EncryptedSessionEvent, FilePreviewMode, FilePreviewResult, GatewayChannelInput, GatewayCommandResult, HistoricalSessionSnapshot, MachineSnapshot, MachineDevExecResult, MachineDiagnostics, ScheduleCommandResult, ScheduleCreateInput, MemoryCommandResult, MemoryMode, MemoryPromoteInput, MemoryWriteInput, ServerMessage, SessionEventPayload, SessionSnapshot, TurnReconcileResult } from "../../shared/dist/index.js";
+import type { DirectoryListing, DaemonLifecycleAction, DaemonLifecycleResult, EncryptedSessionEvent, FilePreviewMode, FilePreviewResult, GatewayChannelInput, GatewayCommandResult, HistoricalSessionSnapshot, MachineSnapshot, MachineDevExecResult, MachineDiagnostics, ScheduleCommandResult, ScheduleCreateInput, MemoryCommandResult, MemoryMode, MemoryPromoteInput, MemoryWriteInput, ServerMessage, SessionEventPayload, SessionSnapshot, TurnReconcileResult } from "../../shared/dist/index.js";
 export type ControllerClientConfig = {
     relayUrl: string;
     controllerToken: string;
@@ -51,6 +51,9 @@ export type ControllerSubscriptionHandlers = {
     onMemoryResult?: (message: Extract<ServerMessage, {
         type: "server:memoryResult";
     }>) => void;
+    onDaemonLifecycleResult?: (message: Extract<ServerMessage, {
+        type: "server:daemonLifecycleResult";
+    }>) => void;
     onTurnReconciled?: (message: Extract<ServerMessage, {
         type: "server:turnReconciled";
     }>) => void;
@@ -290,6 +293,19 @@ export type MachineDevExecInput = {
     timeoutMs?: number;
     waitTimeoutMs?: number;
 };
+export type DaemonLifecycleInput = {
+    machineId: string;
+    action: DaemonLifecycleAction;
+    targetVersion?: string;
+    packageUrl?: string;
+    sha256?: string;
+    tail?: number;
+    waitTimeoutMs?: number;
+};
+export type DaemonLifecycleResponse = DaemonLifecycleResult & {
+    requestId: string;
+    machineId: string;
+};
 export type GatewayCommandInput = {
     machineId: string;
     action: "list" | "get" | "upsert" | "enable" | "disable" | "test";

package/packages/shared/dist/protocol-schemas.d.ts

@@ -94,6 +94,7 @@ export declare const capabilitiesSchema: z.ZodObject<{
     directoryBrowser: z.ZodOptional<z.ZodBoolean>;
     filePreview: z.ZodOptional<z.ZodBoolean>;
     devTools: z.ZodOptional<z.ZodBoolean>;
+    daemonLifecycle: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const machineSnapshotSchema: z.ZodObject<{
     id: z.ZodString;
@@ -182,6 +183,7 @@ export declare const machineSnapshotSchema: z.ZodObject<{
         directoryBrowser: z.ZodOptional<z.ZodBoolean>;
         filePreview: z.ZodOptional<z.ZodBoolean>;
         devTools: z.ZodOptional<z.ZodBoolean>;
+        daemonLifecycle: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     encryptedMetadata: z.ZodOptional<z.ZodObject<{
         v: z.ZodLiteral<1>;
@@ -413,14 +415,88 @@ export declare const machineDevExecResultSchema: z.ZodObject<{
     durationMs: z.ZodNumber;
     timedOut: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
+export declare const daemonUpdateStateSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    action: z.ZodEnum<{
+        restart: "restart";
+        update: "update";
+    }>;
+    targetVersion: z.ZodOptional<z.ZodString>;
+    packageSpec: z.ZodOptional<z.ZodString>;
+    packageUrl: z.ZodOptional<z.ZodString>;
+    sha256: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        running: "running";
+        failed: "failed";
+        accepted: "accepted";
+        stopping: "stopping";
+        installing: "installing";
+        starting: "starting";
+        succeeded: "succeeded";
+    }>;
+    fromVersion: z.ZodString;
+    toVersion: z.ZodOptional<z.ZodString>;
+    startedAt: z.ZodString;
+    finishedAt: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    logPath: z.ZodString;
+}, z.core.$strip>;
+export declare const daemonLifecycleResultSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        status: "status";
+        restart: "restart";
+        update: "update";
+        logs: "logs";
+    }>;
+    accepted: z.ZodOptional<z.ZodBoolean>;
+    version: z.ZodOptional<z.ZodString>;
+    pid: z.ZodOptional<z.ZodNumber>;
+    running: z.ZodOptional<z.ZodBoolean>;
+    platform: z.ZodOptional<z.ZodString>;
+    arch: z.ZodOptional<z.ZodString>;
+    installMode: z.ZodOptional<z.ZodEnum<{
+        "npm-global": "npm-global";
+        "repo-dev": "repo-dev";
+        unknown: "unknown";
+    }>>;
+    updateSupported: z.ZodOptional<z.ZodBoolean>;
+    updateUnsupportedReason: z.ZodOptional<z.ZodString>;
+    updateState: z.ZodOptional<z.ZodObject<{
+        requestId: z.ZodString;
+        action: z.ZodEnum<{
+            restart: "restart";
+            update: "update";
+        }>;
+        targetVersion: z.ZodOptional<z.ZodString>;
+        packageSpec: z.ZodOptional<z.ZodString>;
+        packageUrl: z.ZodOptional<z.ZodString>;
+        sha256: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            running: "running";
+            failed: "failed";
+            accepted: "accepted";
+            stopping: "stopping";
+            installing: "installing";
+            starting: "starting";
+            succeeded: "succeeded";
+        }>;
+        fromVersion: z.ZodString;
+        toVersion: z.ZodOptional<z.ZodString>;
+        startedAt: z.ZodString;
+        finishedAt: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+        logPath: z.ZodString;
+    }, z.core.$strip>>;
+    logs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
 export declare const turnReconcileResultSchema: z.ZodObject<{
     sessionId: z.ZodString;
     turnId: z.ZodOptional<z.ZodString>;
     requestId: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<{
+        unknown: "unknown";
         active: "active";
         terminal: "terminal";
-        unknown: "unknown";
         not_found: "not_found";
         uninspectable: "uninspectable";
     }>;
@@ -1359,12 +1435,12 @@ export declare const memoryTurnOptionsSchema: z.ZodObject<{
 export declare const memoryCommandResultSchema: z.ZodObject<{
     action: z.ZodEnum<{
         search: "search";
+        status: "status";
         overview: "overview";
         read: "read";
         reindex: "reindex";
         write: "write";
         promote: "promote";
-        status: "status";
         sync: "sync";
     }>;
     overview: z.ZodOptional<z.ZodObject<{

package/packages/shared/dist/protocol-schemas.js

@@ -53,6 +53,7 @@ export const capabilitiesSchema = z.object({
     directoryBrowser: z.boolean().optional(),
     filePreview: z.boolean().optional(),
     devTools: z.boolean().optional(),
+    daemonLifecycle: z.boolean().optional(),
 });
 const sessionCapabilitiesSchema = z.object({
     resume: z.enum(["acpx", "native", "checkpoint", "unsupported"]),
@@ -198,6 +199,35 @@ export const machineDevExecResultSchema = z.object({
     durationMs: z.number().nonnegative(),
     timedOut: z.boolean().optional(),
 });
+export const daemonUpdateStateSchema = z.object({
+    requestId: z.string().min(1),
+    action: z.enum(["restart", "update"]),
+    targetVersion: z.string().min(1).optional(),
+    packageSpec: z.string().min(1).optional(),
+    packageUrl: z.string().min(1).optional(),
+    sha256: z.string().regex(/^[a-fA-F0-9]{64}$/).optional(),
+    status: z.enum(["accepted", "running", "stopping", "installing", "starting", "succeeded", "failed"]),
+    fromVersion: z.string().min(1),
+    toVersion: z.string().min(1).optional(),
+    startedAt: z.string().min(1),
+    finishedAt: z.string().min(1).optional(),
+    error: z.string().optional(),
+    logPath: z.string().min(1),
+});
+export const daemonLifecycleResultSchema = z.object({
+    action: z.enum(["status", "restart", "update", "logs"]),
+    accepted: z.boolean().optional(),
+    version: z.string().min(1).optional(),
+    pid: z.number().int().positive().optional(),
+    running: z.boolean().optional(),
+    platform: z.string().min(1).optional(),
+    arch: z.string().min(1).optional(),
+    installMode: z.enum(["npm-global", "repo-dev", "unknown"]).optional(),
+    updateSupported: z.boolean().optional(),
+    updateUnsupportedReason: z.string().min(1).optional(),
+    updateState: daemonUpdateStateSchema.optional(),
+    logs: z.array(z.string()).optional(),
+});
 export const turnReconcileResultSchema = z.object({
     sessionId: z.string().min(1),
     turnId: z.string().min(1).optional(),

package/packages/shared/dist/protocol-types.d.ts

@@ -46,6 +46,7 @@ export type MachineSnapshot = {
         directoryBrowser?: boolean;
         filePreview?: boolean;
         devTools?: boolean;
+        daemonLifecycle?: boolean;
     };
     encryptedMetadata?: EncryptedEnvelope;
 };
@@ -175,6 +176,38 @@ export type MachineDevExecResult = {
     durationMs: number;
     timedOut?: boolean;
 };
+export type DaemonLifecycleAction = "status" | "restart" | "update" | "logs";
+export type DaemonInstallMode = "npm-global" | "repo-dev" | "unknown";
+export type DaemonUpdateStatus = "accepted" | "running" | "stopping" | "installing" | "starting" | "succeeded" | "failed";
+export type DaemonUpdateState = {
+    requestId: string;
+    action: "restart" | "update";
+    targetVersion?: string;
+    packageSpec?: string;
+    packageUrl?: string;
+    sha256?: string;
+    status: DaemonUpdateStatus;
+    fromVersion: string;
+    toVersion?: string;
+    startedAt: string;
+    finishedAt?: string;
+    error?: string;
+    logPath: string;
+};
+export type DaemonLifecycleResult = {
+    action: DaemonLifecycleAction;
+    accepted?: boolean;
+    version?: string;
+    pid?: number;
+    running?: boolean;
+    platform?: string;
+    arch?: string;
+    installMode?: DaemonInstallMode;
+    updateSupported?: boolean;
+    updateUnsupportedReason?: string;
+    updateState?: DaemonUpdateState;
+    logs?: string[];
+};
 export type TurnInspectionStatus = "active" | "terminal" | "unknown" | "not_found" | "uninspectable";
 export type TurnReconcileResult = {
     sessionId: string;

package/packages/shared/dist/protocol.d.ts

@@ -1,7 +1,7 @@
 import type { EncryptedEnvelope } from "./crypto.js";
-import type { DirectoryListing, EncryptedSessionEvent, EncryptedTranscriptReplacementEvent, FilePreviewMode, FilePreviewResult, GatewayChannelInput, GatewayCommandResult, HistoricalSessionSnapshot, MachineDevExecResult, MachineDiagnostics, MachineSnapshot, MemoryCommandResult, MemoryMode, MemoryPromoteInput, MemoryWriteInput, PermissionMode, ScheduleCommandResult, ScheduleCreateInput, SessionHeadAdvanceBasis, SessionSnapshot, TurnReconcileResult } from "./protocol-types.js";
+import type { DirectoryListing, DaemonLifecycleAction, DaemonLifecycleResult, EncryptedSessionEvent, EncryptedTranscriptReplacementEvent, FilePreviewMode, FilePreviewResult, GatewayChannelInput, GatewayCommandResult, HistoricalSessionSnapshot, MachineDevExecResult, MachineDiagnostics, MachineSnapshot, MemoryCommandResult, MemoryMode, MemoryPromoteInput, MemoryWriteInput, PermissionMode, ScheduleCommandResult, ScheduleCreateInput, SessionHeadAdvanceBasis, SessionSnapshot, TurnReconcileResult } from "./protocol-types.js";
 export { encryptedEnvelopeSchema } from "./protocol-schemas.js";
-export type { AgentProfile, DirectoryEntry, DirectoryListing, EncryptedSessionEvent, EncryptedTranscriptReplacementEvent, FilePreviewKind, FilePreviewMode, FilePreviewResult, GatewayChannelInput, GatewayChannelDomain, GatewayDestination, GatewayEventPayload, GatewayInboundMode, GatewayLastDeliveredMessage, GatewayLastMessageRef, GatewayChannelPublic, GatewayChannelType, GatewayCommandResult, GatewayDeliveryResult, GatewayProcessingReactionConfig, HistoricalSessionSnapshot, MachineDevExecResult, MachineDiagnostics, MachineSnapshot, MemoryCitation, MemoryCommandResult, MemoryFileSummary, MemoryLayer, MemoryMode, MemoryOverview, MemoryPromoteInput, MemorySearchResult, MemorySyncConflict, MemoryTurnOptions, MemoryWriteInput, PairingClaimRequest, PairingClaimResponse, PairingStartRequest, PairingStartResponse, PermissionMode, ScheduleCommandResult, ScheduleCreateInput, ScheduleExecution, ScheduleMemoryMode, ScheduleRecord, ScheduleRunRecord, ScheduleSpec, ScheduleStopReason, ScheduleTarget, SessionHeadAdvanceBasis, SessionEventPayload, SessionSnapshot, SessionUsageSnapshot, TurnInspectionStatus, TurnReconcileResult, } from "./protocol-types.js";
+export type { AgentProfile, DaemonInstallMode, DaemonLifecycleAction, DaemonLifecycleResult, DaemonUpdateState, DaemonUpdateStatus, DirectoryEntry, DirectoryListing, EncryptedSessionEvent, EncryptedTranscriptReplacementEvent, FilePreviewKind, FilePreviewMode, FilePreviewResult, GatewayChannelInput, GatewayChannelDomain, GatewayDestination, GatewayEventPayload, GatewayInboundMode, GatewayLastDeliveredMessage, GatewayLastMessageRef, GatewayChannelPublic, GatewayChannelType, GatewayCommandResult, GatewayDeliveryResult, GatewayProcessingReactionConfig, HistoricalSessionSnapshot, MachineDevExecResult, MachineDiagnostics, MachineSnapshot, MemoryCitation, MemoryCommandResult, MemoryFileSummary, MemoryLayer, MemoryMode, MemoryOverview, MemoryPromoteInput, MemorySearchResult, MemorySyncConflict, MemoryTurnOptions, MemoryWriteInput, PairingClaimRequest, PairingClaimResponse, PairingStartRequest, PairingStartResponse, PermissionMode, ScheduleCommandResult, ScheduleCreateInput, ScheduleExecution, ScheduleMemoryMode, ScheduleRecord, ScheduleRunRecord, ScheduleSpec, ScheduleStopReason, ScheduleTarget, SessionHeadAdvanceBasis, SessionEventPayload, SessionSnapshot, SessionUsageSnapshot, TurnInspectionStatus, TurnReconcileResult, } from "./protocol-types.js";
 export type ControllerClientMessage = {
     type: "controller:createSession";
     requestId: string;
@@ -80,6 +80,15 @@ export type ControllerClientMessage = {
     cwd?: string;
     shell?: string;
     timeoutMs?: number;
+} | {
+    type: "controller:daemonLifecycle";
+    requestId: string;
+    machineId: string;
+    action: DaemonLifecycleAction;
+    targetVersion?: string;
+    packageUrl?: string;
+    sha256?: string;
+    tail?: number;
 } | {
     type: "controller:gateway";
     requestId: string;
@@ -233,6 +242,11 @@ export type MachineClientMessage = {
     requestId: string;
     machineId: string;
     result: MachineDevExecResult;
+} | {
+    type: "machine:daemonLifecycleResult";
+    requestId: string;
+    machineId: string;
+    result: DaemonLifecycleResult;
 } | {
     type: "machine:gatewayResult";
     requestId: string;
@@ -388,6 +402,15 @@ export type MachineCommand = {
     cwd?: string;
     shell?: string;
     timeoutMs?: number;
+} | {
+    type: "machine:daemonLifecycle";
+    requestId: string;
+    machineId: string;
+    action: DaemonLifecycleAction;
+    targetVersion?: string;
+    packageUrl?: string;
+    sha256?: string;
+    tail?: number;
 } | {
     type: "machine:gateway";
     requestId: string;
@@ -520,6 +543,11 @@ export type ServerMessage = {
     requestId: string;
     machineId: string;
     result: MachineDevExecResult;
+} | {
+    type: "server:daemonLifecycleResult";
+    requestId: string;
+    machineId: string;
+    result: DaemonLifecycleResult;
 } | {
     type: "server:gatewayResult";
     requestId: string;

package/packages/shared/dist/protocol.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { capabilitiesSchema, directoryEntrySchema, encryptedEnvelopeSchema, encryptedSessionEventSchema, encryptedTranscriptReplacementEventSchema, filePreviewResultSchema, gatewayChannelInputSchema, gatewayCommandResultSchema, historicalSessionSnapshotSchema, machineDevExecResultSchema, machineDiagnosticsSchema, machineSnapshotSchema, memoryCommandResultSchema, memoryPromoteInputSchema, memoryWriteInputSchema, scheduleCommandResultSchema, scheduleCreateInputSchema, sessionSnapshotSchema, turnReconcileResultSchema, } from "./protocol-schemas.js";
+import { capabilitiesSchema, daemonLifecycleResultSchema, directoryEntrySchema, encryptedEnvelopeSchema, encryptedSessionEventSchema, encryptedTranscriptReplacementEventSchema, filePreviewResultSchema, gatewayChannelInputSchema, gatewayCommandResultSchema, historicalSessionSnapshotSchema, machineDevExecResultSchema, machineDiagnosticsSchema, machineSnapshotSchema, memoryCommandResultSchema, memoryPromoteInputSchema, memoryWriteInputSchema, scheduleCommandResultSchema, scheduleCreateInputSchema, sessionSnapshotSchema, turnReconcileResultSchema, } from "./protocol-schemas.js";
 import { isSessionNameValid } from "./session-name.js";
 export { encryptedEnvelopeSchema } from "./protocol-schemas.js";
 const controllerMessageSchema = z.discriminatedUnion("type", [
@@ -92,6 +92,16 @@ const controllerMessageSchema = z.discriminatedUnion("type", [
         shell: z.string().optional(),
         timeoutMs: z.number().int().positive().max(600_000).optional(),
     }),
+    z.object({
+        type: z.literal("controller:daemonLifecycle"),
+        requestId: z.string().min(1),
+        machineId: z.string().min(1),
+        action: z.enum(["status", "restart", "update", "logs"]),
+        targetVersion: z.string().min(1).optional(),
+        packageUrl: z.string().min(1).optional(),
+        sha256: z.string().regex(/^[a-fA-F0-9]{64}$/).optional(),
+        tail: z.number().int().positive().max(2000).optional(),
+    }),
     z.object({
         type: z.literal("controller:gateway"),
         requestId: z.string().min(1),
@@ -283,6 +293,12 @@ const machineMessageSchema = z.discriminatedUnion("type", [
         machineId: z.string().min(1),
         result: machineDevExecResultSchema,
     }),
+    z.object({
+        type: z.literal("machine:daemonLifecycleResult"),
+        requestId: z.string().min(1),
+        machineId: z.string().min(1),
+        result: daemonLifecycleResultSchema,
+    }),
     z.object({
         type: z.literal("machine:gatewayResult"),
         requestId: z.string().min(1),
@@ -463,6 +479,16 @@ const machineCommandSchema = z.discriminatedUnion("type", [
         shell: z.string().optional(),
         timeoutMs: z.number().int().positive().max(600_000).optional(),
     }),
+    z.object({
+        type: z.literal("machine:daemonLifecycle"),
+        requestId: z.string().min(1),
+        machineId: z.string().min(1),
+        action: z.enum(["status", "restart", "update", "logs"]),
+        targetVersion: z.string().min(1).optional(),
+        packageUrl: z.string().min(1).optional(),
+        sha256: z.string().regex(/^[a-fA-F0-9]{64}$/).optional(),
+        tail: z.number().int().positive().max(2000).optional(),
+    }),
     z.object({
         type: z.literal("machine:gateway"),
         requestId: z.string().min(1),
@@ -624,6 +650,12 @@ const serverMessageSchema = z.union([
         machineId: z.string().min(1),
         result: machineDevExecResultSchema,
     }),
+    z.object({
+        type: z.literal("server:daemonLifecycleResult"),
+        requestId: z.string().min(1),
+        machineId: z.string().min(1),
+        result: daemonLifecycleResultSchema,
+    }),
     z.object({
         type: z.literal("server:gatewayResult"),
         requestId: z.string().min(1),