@telepath-computer/television 1.4.7 → 1.4.8

package/dist/cli.cjs

@@ -34472,12 +34472,14 @@ var import_node_url = require("node:url");
 
 // ../server/src/config.ts
 var import_node_fs2 = require("node:fs");
+var import_node_net = require("node:net");
 var import_node_os2 = __toESM(require("node:os"), 1);
 var import_node_path2 = __toESM(require("node:path"), 1);
 var TRUE_ENV_VALUE = "true";
 var APP_HIDDEN_DIRECTORY = ".television";
-var TELEVISION_STORAGE_PATH_ENV = "TELEVISION_STORAGE_PATH";
-var TELEVISION_PORT_ENV = "TELEVISION_PORT";
+var HOME_POINTER_FILE = ".tv-home";
+var CONFIG_FILE = "config.json";
+var CONFIG_KEYS = ["port", "listen", "auth", "installedByAgent"];
 var TELEVISION_ACP_AGENT_ENV = "TELEVISION_ACP_AGENT";
 var TELEVISION_DEVELOPER_HOME_ENV = "TELEVISION_DEVELOPER_HOME";
 var MAX_PORT = 65535;
@@ -34513,25 +34515,153 @@ var DEFAULT_SERVER_URL = buildServerURL(DEFAULT_SERVER_HOST, DEFAULT_SERVER_PORT
 function buildServerURL(host, port) {
   return `http://${host}:${port}`;
 }
-function getDefaultTelevisionStoragePath() {
-  return import_node_path2.default.join(import_node_os2.default.homedir(), APP_HIDDEN_DIRECTORY);
+var TelevisionConfigError = class extends Error {
+  configPath;
+  constructor(configPath, message) {
+    super(message);
+    this.name = "TelevisionConfigError";
+    this.configPath = configPath;
+  }
+};
+function resolveTelevisionHome(input) {
+  const { homeOption, operatingSystemHomeDir, cwd } = input;
+  if (homeOption !== void 0) {
+    if (homeOption.trim() === "") {
+      throw new Error("--home requires a path; an empty value does not select the default home.");
+    }
+    return import_node_path2.default.resolve(cwd, homeOption);
+  }
+  const pointerPath = import_node_path2.default.join(operatingSystemHomeDir, HOME_POINTER_FILE);
+  const builtInHome = import_node_path2.default.join(operatingSystemHomeDir, APP_HIDDEN_DIRECTORY);
+  let contents;
+  try {
+    contents = (0, import_node_fs2.readFileSync)(pointerPath, "utf8");
+  } catch (error48) {
+    if (isMissingFileError(error48)) return builtInHome;
+    throw new Error(`${pointerPath} cannot be read: ${errorMessage(error48)}`);
+  }
+  const pointer = contents.trim();
+  if (pointer === "") {
+    throw new Error(`${pointerPath} holds no path. Write the Television home's path in it, or delete it to use ${builtInHome}.`);
+  }
+  if (/[\r\n]/.test(pointer)) {
+    throw new Error(`${pointerPath} holds more than one line. It must hold only the Television home's path.`);
+  }
+  if (pointer === "~" || pointer.startsWith("~/")) {
+    return import_node_path2.default.resolve(import_node_path2.default.join(operatingSystemHomeDir, pointer.slice(1)));
+  }
+  if (pointer.startsWith("~")) {
+    throw new Error(`${pointerPath} holds ${pointer}, but ~ followed by a user name is not supported. Use an absolute path instead.`);
+  }
+  return import_node_path2.default.resolve(operatingSystemHomeDir, pointer);
 }
-function getTelevisionStoragePath() {
-  return process.env[TELEVISION_STORAGE_PATH_ENV] ?? getDefaultTelevisionStoragePath();
+function readTelevisionConfig(home) {
+  const configPath = getConfigPath(home);
+  const stored = readStoredConfig(configPath);
+  if (stored === void 0) return buildConfig(configPath, false, {});
+  return buildConfig(configPath, true, validateConfigFile(configPath, stored));
 }
-function getTelevisionPortEnv() {
-  const rawPort = process.env[TELEVISION_PORT_ENV];
-  if (rawPort === void 0 || rawPort.trim() === "") {
-    return void 0;
+function updateTelevisionConfig(home, changes) {
+  const configPath = getConfigPath(home);
+  const merged = { ...readStoredConfig(configPath) };
+  for (const [key, value] of Object.entries(changes)) {
+    if (value !== void 0) merged[key] = value;
   }
-  if (!/^\d+$/.test(rawPort)) {
-    throw new Error(`${TELEVISION_PORT_ENV} must be a decimal integer between 0 and ${MAX_PORT}.`);
+  const file2 = validateConfigFile(configPath, merged);
+  const resolvedHome = import_node_path2.default.dirname(configPath);
+  (0, import_node_fs2.mkdirSync)(resolvedHome, { recursive: true });
+  const temporaryPath = import_node_path2.default.join(resolvedHome, `.${CONFIG_FILE}.${process.pid}.${Date.now()}.tmp`);
+  try {
+    (0, import_node_fs2.writeFileSync)(temporaryPath, `${JSON.stringify(merged, null, 2)}
+`, { flag: "wx" });
+    (0, import_node_fs2.renameSync)(temporaryPath, configPath);
+  } catch (error48) {
+    (0, import_node_fs2.rmSync)(temporaryPath, { force: true });
+    throw error48;
   }
-  const port = Number(rawPort);
-  if (!Number.isSafeInteger(port) || port < 0 || port > MAX_PORT) {
-    throw new Error(`${TELEVISION_PORT_ENV} must be a decimal integer between 0 and ${MAX_PORT}.`);
+  return buildConfig(configPath, true, file2);
+}
+function getConfigPath(home) {
+  return import_node_path2.default.join(import_node_path2.default.resolve(home), CONFIG_FILE);
+}
+function readStoredConfig(configPath) {
+  let contents;
+  try {
+    contents = (0, import_node_fs2.readFileSync)(configPath, "utf8");
+  } catch (error48) {
+    if (isMissingFileError(error48)) return void 0;
+    throw new TelevisionConfigError(configPath, `Config file ${configPath} cannot be read: ${errorMessage(error48)}`);
   }
-  return port;
+  let parsed;
+  try {
+    parsed = JSON.parse(contents);
+  } catch (error48) {
+    throw new TelevisionConfigError(configPath, `Config file ${configPath} is not valid JSON: ${errorMessage(error48)}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    const found = Array.isArray(parsed) ? "an array" : parsed === null ? "null" : `a ${typeof parsed}`;
+    throw new TelevisionConfigError(configPath, `Config file ${configPath} must hold a JSON object, not ${found}.`);
+  }
+  return parsed;
+}
+function validateConfigFile(configPath, stored) {
+  const invalid = (problem) => new TelevisionConfigError(configPath, `Config file ${configPath}: ${problem}`);
+  const file2 = {};
+  for (const [key, value] of Object.entries(stored)) {
+    const found = `got ${JSON.stringify(value)}`;
+    switch (key) {
+      case "port":
+        if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > MAX_PORT) {
+          throw invalid(`"port" must be a whole number from 0 through ${MAX_PORT}; ${found}.`);
+        }
+        file2.port = value;
+        break;
+      case "listen":
+        if (!Array.isArray(value)) {
+          throw invalid(`"listen" must be an array of IPv4 address strings; ${found}.`);
+        }
+        for (const item of value) {
+          if (typeof item !== "string" || !(0, import_node_net.isIPv4)(item)) {
+            throw invalid(`each "listen" item must be an IPv4 address string; got ${JSON.stringify(item)}.`);
+          }
+        }
+        file2.listen = [...value];
+        break;
+      case "auth":
+        if (typeof value !== "boolean") {
+          throw invalid(`"auth" must be true or false; ${found}.`);
+        }
+        file2.auth = value;
+        break;
+      case "installedByAgent":
+        if (typeof value !== "string") {
+          throw invalid(`"installedByAgent" must be a string; ${found}.`);
+        }
+        file2.installedByAgent = value;
+        break;
+      default:
+        throw invalid(`unknown key ${JSON.stringify(key)}. Valid keys are ${CONFIG_KEYS.join(", ")}.`);
+    }
+  }
+  return file2;
+}
+function buildConfig(configPath, configFileExists, file2) {
+  const settings = {
+    port: file2.port ?? DEFAULT_SERVER_PORT,
+    listen: file2.listen ?? [],
+    auth: file2.auth ?? true
+  };
+  if (file2.installedByAgent !== void 0) settings.installedByAgent = file2.installedByAgent;
+  return { home: import_node_path2.default.dirname(configPath), configPath, configFileExists, settings };
+}
+function isMissingFileError(error48) {
+  return error48?.code === "ENOENT";
+}
+function errorMessage(error48) {
+  return error48 instanceof Error ? error48.message : String(error48);
+}
+function getDefaultTelevisionStoragePath() {
+  return import_node_path2.default.join(import_node_os2.default.homedir(), APP_HIDDEN_DIRECTORY);
 }
 function resolveACPAgentProfile(env = process.env) {
   const rawAgent = env[TELEVISION_ACP_AGENT_ENV];
@@ -48942,7 +49072,7 @@ function isNewerVersion(candidate, baseline) {
 }
 
 // ../server/src/telemetry/derivation.ts
-var import_node_net = require("node:net");
+var import_node_net2 = require("node:net");
 
 // ../../node_modules/ulid/dist/node/index.js
 var import_node_crypto = __toESM(require("node:crypto"), 1);
@@ -49943,7 +50073,7 @@ function isLoopbackAddress(address) {
   return normalized === "localhost" || normalized === "::1" || normalized === "[::1]" || normalized.startsWith("127.");
 }
 function isTailnetIPv4(hostname3) {
-  if ((0, import_node_net.isIP)(hostname3) !== IPV4_VERSION) return false;
+  if ((0, import_node_net2.isIP)(hostname3) !== IPV4_VERSION) return false;
   const [a, b2] = hostname3.split(".").map((part) => Number.parseInt(part, 10));
   return a === TAILNET_FIRST_OCTET && b2 !== void 0 && b2 >= TAILNET_MIN_SECOND_OCTET && b2 <= TAILNET_MAX_SECOND_OCTET;
 }
@@ -52744,6 +52874,11 @@ function trackChild(child) {
   child.once("error", untrack);
 }
 var ACP_STUB_CWD = import_node_path8.default.join((0, import_node_os4.homedir)(), ".television", "acp");
+function buildACPAgentTVArgs(input) {
+  const args = ["--home", import_node_path8.default.resolve(input.home)];
+  if (input.configuredPort === 0) args.push("--port", String(input.acquiredPort));
+  return args;
+}
 var ACPBridge = class extends withDisposable(class {
 }) {
   child = null;
@@ -52753,12 +52888,14 @@ var ACPBridge = class extends withDisposable(class {
   stderrBuffer = "";
   send;
   profile;
+  tvArgs;
   launchProcess;
   sessionCwd;
   constructor(options) {
     super();
     this.send = options.send;
     this.profile = options.profile;
+    this.tvArgs = options.tvArgs;
     this.launchProcess = options.launchProcess ?? launchACPProcess;
     this.sessionCwd = import_node_path8.default.resolve(process.cwd());
   }
@@ -52887,7 +53024,8 @@ var ACPBridge = class extends withDisposable(class {
         status: "ready",
         agent: this.profile.agent,
         sessionIdStrategy: this.profile.sessionIdStrategy,
-        sessionCwd: this.sessionCwd
+        sessionCwd: this.sessionCwd,
+        tvArgs: [...this.tvArgs]
       });
       return;
     }
@@ -52912,6 +53050,7 @@ var ACPServer = class extends withDisposable(class {
   authToken;
   authRequired;
   profile;
+  getAgentTVArgs;
   constructor(options) {
     super();
     if (!options.profile) {
@@ -52920,6 +53059,7 @@ var ACPServer = class extends withDisposable(class {
     this.authToken = options.authToken;
     this.authRequired = options.authRequired;
     this.profile = options.profile;
+    this.getAgentTVArgs = options.getAgentTVArgs;
     this.wsServer = new import_websocket_server.default({ noServer: true });
     this.wsServer.on("connection", (socket, request) => {
       if (this.authRequired && !isAuthorizedQueryToken(request.url, this.authToken)) {
@@ -52928,6 +53068,7 @@ var ACPServer = class extends withDisposable(class {
       }
       const bridge = new ACPBridge({
         profile: this.profile,
+        tvArgs: this.getAgentTVArgs(),
         send: (message) => {
           if (socket.readyState === import_websocket.default.OPEN) {
             socket.send(JSON.stringify(message));
@@ -52977,14 +53118,14 @@ var ACPServer = class extends withDisposable(class {
 };
 
 // ../server/src/bind-addresses.ts
-var import_node_net2 = require("node:net");
+var import_node_net3 = require("node:net");
 var LOCALHOST_IPV4 = "127.0.0.1";
 var ANY_IPV4 = "0.0.0.0";
 function resolveBindAddresses(listenValues = []) {
   const addresses = [LOCALHOST_IPV4];
   for (const address of splitListenValues(listenValues)) {
-    if (!(0, import_node_net2.isIPv4)(address)) {
-      throw new Error(`Invalid --listen address \`${address}\`. Use an IPv4 address.`);
+    if (!(0, import_node_net3.isIPv4)(address)) {
+      throw new Error(`Invalid listen address \`${address}\`. Use an IPv4 address.`);
     }
     addresses.push(address);
   }
@@ -53216,7 +53357,7 @@ var StartupBindError = class extends Error {
     this.name = "StartupBindError";
   }
 };
-function buildStartupBindFailureRecord(attempts) {
+function buildStartupBindFailureRecord(attempts, launchMode) {
   return {
     reason: "required-listener-bind-failed",
     exitStatus: STARTUP_BIND_EXIT_STATUS,
@@ -53231,7 +53372,7 @@ function buildStartupBindFailureRecord(attempts) {
         ...code === void 0 ? {} : { code },
         ...typeof serializedError.syscall === "string" ? { syscall: serializedError.syscall } : {},
         cause: bindFailureCause(attempt, code),
-        hint: bindFailureHint(attempt, code)
+        hint: bindFailureHint(attempt, code, launchMode)
       };
     })
   };
@@ -53248,9 +53389,9 @@ function bindFailureCause(attempt, code) {
   }
   return `Cannot bind ${attempt.address}:${attempt.port}: ${attempt.error.message}`;
 }
-function bindFailureHint(attempt, code) {
-  if (code === "EADDRNOTAVAIL" && isCgnatAddress(attempt.address)) {
-    return `Address ${attempt.address} is not assigned to any interface. If this is a Tailscale IP, tailscaled may not be up yet (transient at boot), or the tailnet IP may have changed (permanent until \`tv serve --persist\` is re-run to refresh the configured address). The service manager will retry.`;
+function bindFailureHint(attempt, code, launchMode) {
+  if (code === "EADDRNOTAVAIL" && launchMode === "daemon" && isCgnatAddress(attempt.address)) {
+    return `Address ${attempt.address} is not assigned to any interface. If this is a Tailscale IP, tailscaled may not be up yet (transient at boot), or the tailnet IP may have changed (permanent until the config file's \`listen\` setting is corrected). The service manager will retry.`;
   }
   if (code === "EADDRNOTAVAIL") {
     return `Confirm that ${attempt.address} is assigned to a local interface, then retry.`;
@@ -53984,7 +54125,7 @@ function disabledTelemetryRuntime() {
 
 // ../server/src/updates/version.ts
 function readVersionStamp() {
-  if ("1.4.7".length > 0) return "1.4.7";
+  if ("1.4.8".length > 0) return "1.4.8";
   return void 0;
 }
 function resolveUpdateReleaseVersion(env = process.env, stamp = readVersionStamp()) {
@@ -54150,7 +54291,6 @@ function parseIntervalOverride(value) {
 // ../server/src/server.ts
 var import_meta = {};
 var HTTP_UNAUTHORIZED_STATUS = 401;
-var LOOPBACK_IPV4 = "127.0.0.1";
 var CANONICAL_VERSION_DIRECTORY_PATTERN = /^v\d+(?:\.\d+)?$/;
 function resolveCanonicalVersionDirectories(canonicalDir) {
   const canonicalRoot = import_node_path13.default.resolve(canonicalDir);
@@ -54185,6 +54325,7 @@ var Server = class {
   authMode;
   bindAddresses;
   telemetryOptions;
+  launchMode;
   telemetryRuntime = null;
   updateChannel = null;
   listeningPort;
@@ -54197,6 +54338,7 @@ var Server = class {
     this.authMode = options.auth === true ? "auth" : options.auth === false ? "no-auth" : "none";
     this.bindAddresses = resolveBindAddresses(options.host ? [options.host] : options.listen);
     this.telemetryOptions = options.telemetry ?? {};
+    this.launchMode = this.telemetryOptions.launchMode ?? "cli";
     this.listeningPort = this.port;
     this.baseURLs = [];
     this.app = (0, import_express2.default)();
@@ -54233,7 +54375,12 @@ var Server = class {
     this.acp = options.acpProfile ? new ACPServer({
       authToken: this.store.authToken,
       authRequired: this.authRequired,
-      profile: options.acpProfile
+      profile: options.acpProfile,
+      getAgentTVArgs: () => buildACPAgentTVArgs({
+        home: this.store.storagePath,
+        configuredPort: this.port,
+        acquiredPort: this.getListeningPort()
+      })
     }) : null;
     registerRoutes(this.app, this.store, {
       requireAuth: this.requireAuthorization,
@@ -54333,7 +54480,11 @@ var Server = class {
       }
     }
     if (attempts.some((attempt) => attempt.outcome === "failed")) {
-      log(this.store.storagePath, "server startup failed", buildStartupBindFailureRecord(attempts));
+      log(
+        this.store.storagePath,
+        "server startup failed",
+        buildStartupBindFailureRecord(attempts, this.launchMode)
+      );
       await Promise.allSettled(boundServers.map((server) => this.closeServer(server)));
       throw new StartupBindError(attempts);
     }
@@ -54348,16 +54499,6 @@ var Server = class {
     log(this.store.storagePath, "server started", { snapshot: this.configurationSnapshot() });
     if (!this.authRequired) {
       log(this.store.storagePath, "server running without bearer-token enforcement", { authMode: this.authMode });
-      const nonLoopbackBoundAddresses = this.getNonLoopbackBoundAddresses();
-      process.stderr.write(
-        "WARNING: running without an auth token. Tokenless mode is insecure for typical setups \u2014 be sure you mean to run without authentication. Start with --auth to require the bearer token.\n"
-      );
-      if (this.authMode === "no-auth" && nonLoopbackBoundAddresses.length > 0) {
-        process.stderr.write(
-          `Non-loopback listeners without auth: ${nonLoopbackBoundAddresses.join(", ")}
-`
-        );
-      }
     }
     return this.httpServer;
   }
@@ -54437,9 +54578,6 @@ var Server = class {
       server.listen(port, address);
     });
   }
-  getNonLoopbackBoundAddresses() {
-    return this.baseURLs.map((url2) => new URL(url2).hostname).filter((address) => address !== LOOPBACK_IPV4);
-  }
   /**
    * Update-channel poller lifecycle (specs/arch/updates/update-channel.md):
    * owned by the Server — started here, stopped in dispose() with its timer
@@ -54454,7 +54592,6 @@ var Server = class {
   }
   async startTelemetry() {
     const version2 = this.telemetryOptions.version ?? readServerPackageVersion();
-    const launchMode = this.telemetryOptions.launchMode ?? "cli";
     const runtime = await createTelemetryRuntime({
       storagePath: this.store.storagePath,
       version: version2,
@@ -54481,7 +54618,7 @@ var Server = class {
         port: this.getListeningPort(),
         bindAddresses: this.bindAddresses,
         authMode: this.authMode,
-        launchMode,
+        launchMode: this.launchMode,
         installedByAgent: this.telemetryOptions.installedByAgent ?? null
       }),
       { telemetry_opted_out: runtime.boot.state.optedOut }
@@ -54530,8 +54667,8 @@ var Server = class {
   };
 };
 function readServerPackageVersion() {
-  if ("1.4.7".length > 0) {
-    return telemetryVersion("1.4.7");
+  if ("1.4.8".length > 0) {
+    return telemetryVersion("1.4.8");
   }
   const packageJsonPath = import_node_path13.default.resolve(import_node_path13.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url)), "..", "package.json");
   if (!(0, import_node_fs11.existsSync)(packageJsonPath)) return telemetryVersion("0.0.0");
@@ -56674,12 +56811,35 @@ var import_meta2 = {};
 var DAEMON_NAME = "com.television.server";
 var TELEMETRY_LAUNCH_MODE_ENV = "TELEVISION_LAUNCH_MODE";
 var SKILL_INSTALL_TELEMETRY_TIMEOUT_MS2 = 1e3;
+var MIN_CLIENT_PORT = 1;
 var MAX_PORT2 = 65535;
 var MAX_PROCESS_EXIT_STATUS = 255;
+var LOOPBACK_IPV4 = "127.0.0.1";
+var CONFIG_KEYS2 = ["port", "listen", "auth", "installedByAgent"];
 var HTTP_UNAUTHORIZED_STATUS2 = 401;
 var HELP_POINTER = "Television ships bundled skills. The main skill is `television` \u2014 keep its guidance available for channels, lifecycle, the `tv` CLI, artifact workflow, and theming. Re-read it only if it is not already in context or you know the installed skill changed. Additional `tv-*` skills cover specialized artifact types. Install all bundled skills with `tv skills install <path>` (e.g. ~/.openclaw/skills) or `tv skills install -i`.";
-var PORT_ZERO_WARNING = "WARNING: --port 0 can make Television hard for later agent CLI commands to rediscover. Use a stable port and export TELEVISION_PORT in the user's environment when agents need to find the server later.";
+var PORT_ZERO_WARNING = "WARNING: config port 0 lets the operating system choose this server's port. Commands that contact this server must pass --port <port>, using the port from the startup URL.";
+var TOKENLESS_WARNING = "WARNING: running without an auth token. Tokenless mode is insecure for typical setups \u2014 be sure you mean to run without authentication. Run `tv config set auth true` and restart to require the bearer token.";
 var SAFE_ARG_PATTERN = /^[A-Za-z0-9_./:@%+=,-]+$/;
+var RETIRED_SERVE_OPTIONS = ["--port", "--listen", "--auth", "--no-auth", "--installed-by-agent"];
+var RETIRED_VALUE_OPTIONS = ["--port", "--listen", "--installed-by-agent", "--storage-path"];
+var ADMIN_GUIDE_URL = "https://television.run/install.md";
+var RETIRED_OPTIONS_GUIDANCE = [
+  "Server settings and the storage directory are no longer command options:",
+  "",
+  "  --port <number>              ->  tv config set port <number>",
+  "  --listen <ipv4>[,<ipv4>...]  ->  tv config set listen <ipv4>[,<ipv4>...]",
+  "  --auth                       ->  tv config set auth true (the default)",
+  "  --no-auth                    ->  tv config set auth false",
+  "  --installed-by-agent <name>  ->  tv config set installedByAgent <name>",
+  "  --storage-path <path>        ->  tv --home <path> <command>, or write <path> into ~/.tv-home",
+  "",
+  "tv config set writes the config file in the Television home. For a home other than the default, put --home <path> before the command name, as in tv --home <path> config set port <number>.",
+  "After changing settings, rerun tv serve --persist to update an installed service.",
+  `The administrator guide covers the full upgrade and is written for your agent to carry out: ${ADMIN_GUIDE_URL}`
+].join("\n");
+var RETIRED_SERVICE_RECORD = "service runs from a retired service definition";
+var LEGACY_VARIABLES_WARNING = "WARNING: TELEVISION_PORT or TELEVISION_STORAGE_PATH is set in this environment, and Television no longer uses either. Set the server's port with tv config set port <number>. Television uses the home given with tv --home <path> <command>, otherwise the path written in ~/.tv-home, otherwise ~/.television.";
 var CLIDirectiveError = class extends Error {
   name = "CLIDirectiveError";
 };
@@ -56737,8 +56897,8 @@ function resolveVercelSkillsInstallerBin() {
   return localRequire.resolve("skills/bin/cli.mjs");
 }
 function readCLIVersion() {
-  if ("1.4.7".length > 0) {
-    return "1.4.7";
+  if ("1.4.8".length > 0) {
+    return "1.4.8";
   }
   const devPackageJsonPath = import_node_path20.default.join(getDevPackageDir(), "package.json");
   if (!(0, import_node_fs18.existsSync)(devPackageJsonPath)) {
@@ -56799,28 +56959,72 @@ function formatEnteredInvocation(argv) {
 function formatEnteredCommand(argv) {
   return argv.length > 0 ? argv.map(formatArgvToken).join(" ") : "tv";
 }
-function storagePathFromArgv(argv) {
+function exitStatusFromError(error48) {
+  if (typeof error48 !== "object" || error48 === null || !("exitStatus" in error48)) return void 0;
+  const exitStatus = error48.exitStatus;
+  return typeof exitStatus === "number" && Number.isInteger(exitStatus) && exitStatus > 0 && exitStatus <= MAX_PROCESS_EXIT_STATUS ? exitStatus : void 0;
+}
+function splitOptionToken(token) {
+  const equals = token.indexOf("=");
+  return token.startsWith("--") && equals !== -1 ? [token.slice(0, equals), token.slice(equals + 1)] : [token, void 0];
+}
+function findCommandName(argv) {
   for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (arg === "--storage-path") {
-      return argv[index + 1];
+    const token = argv[index];
+    if (token === "--") return void 0;
+    if (!token.startsWith("-")) return token;
+    if (token === "--home" || RETIRED_VALUE_OPTIONS.includes(token)) index += 1;
+  }
+  return void 0;
+}
+function extractRetiredOptions(argv) {
+  const command = findCommandName(argv);
+  const retired = [];
+  const remaining = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--") {
+      remaining.push(...argv.slice(index));
+      break;
     }
-    if (arg.startsWith("--storage-path=")) {
-      return arg.slice("--storage-path=".length);
+    const [name, inlineValue] = splitOptionToken(token);
+    const isRetired = name === "--storage-path" || command === "serve" && RETIRED_SERVE_OPTIONS.includes(name);
+    if (!isRetired) {
+      remaining.push(token);
+    } else if (inlineValue !== void 0 || !RETIRED_VALUE_OPTIONS.includes(name)) {
+      retired.push({ name, value: inlineValue });
+    } else {
+      retired.push({ name, value: argv[index + 1] });
+      index += 1;
     }
   }
-  return void 0;
+  return { command, retired, remaining };
 }
-function exitStatusFromError(error48) {
-  if (typeof error48 !== "object" || error48 === null || !("exitStatus" in error48)) return void 0;
-  const exitStatus = error48.exitStatus;
-  return typeof exitStatus === "number" && Number.isInteger(exitStatus) && exitStatus > 0 && exitStatus <= MAX_PROCESS_EXIT_STATUS ? exitStatus : void 0;
+function readRetiredServiceDefinition(command, retired, remaining, processEnv) {
+  const options = remaining.slice(0, remaining.includes("--") ? remaining.indexOf("--") : void 0);
+  const otherForm = options.some((token) => ["--persist", "--persist-uninstall", "--home"].includes(splitOptionToken(token)[0]));
+  if (resolveTelemetryLaunchMode(processEnv) !== "daemon" || command !== "serve" || otherForm) return void 0;
+  const values = (name) => retired.filter((option) => option.name === name).map((option) => option.value ?? "");
+  const settings = { auth: values("--auth").length > 0 };
+  const port = values("--port").at(-1);
+  if (port !== void 0) {
+    settings.port = parseWholePort(port, 0) ?? port;
+  } else {
+    const environmentPort = parseWholePort(processEnv.TELEVISION_PORT ?? "", 0);
+    if (environmentPort !== void 0) settings.port = environmentPort;
+  }
+  const listen = values("--listen");
+  if (listen.length > 0) settings.listen = listen.flatMap((value) => value.split(",").map((address) => address.trim()).filter(Boolean));
+  const installedByAgent = values("--installed-by-agent").at(-1);
+  if (installedByAgent !== void 0) settings.installedByAgent = installedByAgent;
+  const storagePath = values("--storage-path").at(-1);
+  return { ...storagePath === void 0 ? {} : { storagePath }, settings };
 }
-function formatCLIError(error48, argv = []) {
+function formatCLIError(error48, invocation) {
   if (error48 instanceof CLIDirectiveError) {
     return error48.message;
   }
-  if (error48 instanceof ValidationError) {
+  if (error48 instanceof ValidationError || error48 instanceof TelevisionConfigError) {
     return ensureHelpPointer(error48.message);
   }
   if (typeof error48 === "object" && error48 !== null && "serverURL" in error48 && "message" in error48) {
@@ -56829,7 +57033,7 @@ function formatCLIError(error48, argv = []) {
     const status = typeof error48.status === "number" ? Number(error48.status) : void 0;
     if (status === HTTP_UNAUTHORIZED_STATUS2) {
       return ensureHelpPointer(
-        `Television server at ${serverURL} rejected the request as unauthorized. Check the token in ${import_node_path20.default.join(storagePathFromArgv(argv) ?? getTelevisionStoragePath(), "state", "token")}.`
+        `Television server at ${serverURL} rejected the request as unauthorized. Check the token in ${import_node_path20.default.join(invocation.home ?? "<home>", "state", "token")}.`
       );
     }
     if (status !== void 0) {
@@ -56839,44 +57043,56 @@ function formatCLIError(error48, argv = []) {
   }
   return error48 instanceof Error ? error48.message : String(error48);
 }
-function parsePortOption(value) {
-  if (!/^\d+$/.test(value)) {
-    throw new InvalidArgumentError(`port must be a decimal integer between 0 and ${MAX_PORT2}`);
-  }
+function parseWholePort(value, minimum) {
+  if (!/^\d+$/.test(value)) return void 0;
   const port = Number(value);
-  if (!Number.isSafeInteger(port) || port < 0 || port > MAX_PORT2) {
-    throw new InvalidArgumentError(`port must be a decimal integer between 0 and ${MAX_PORT2}`);
-  }
-  return port;
-}
-function collectOption(value, previous = []) {
-  return [...previous, value];
+  return Number.isSafeInteger(port) && port >= minimum && port <= MAX_PORT2 ? port : void 0;
 }
-function resolveClientPort(port) {
-  if (port !== void 0) {
-    return port;
+function parseClientPortOption(value) {
+  const port = parseWholePort(value, MIN_CLIENT_PORT);
+  if (port === void 0) {
+    throw new InvalidArgumentError(`port must be a whole decimal integer from ${MIN_CLIENT_PORT} through ${MAX_PORT2}`);
   }
-  try {
-    return getTelevisionPortEnv() ?? DEFAULT_SERVER_PORT;
-  } catch (error48) {
-    throw createDirectiveError(error48 instanceof Error ? error48.message : String(error48));
-  }
-}
-function buildLocalServerURL(port) {
-  return buildServerURL(DEFAULT_SERVER_HOST, resolveClientPort(port));
+  return port;
 }
-function resolveServeAuth(argv, hasListen) {
-  const wantsAuth = argv.includes("--auth");
-  const wantsNoAuth = argv.includes("--no-auth");
-  if (wantsAuth && wantsNoAuth) {
-    throw createDirectiveError("Use either `--auth` or `--no-auth`, not both.");
-  }
-  if (hasListen && !wantsAuth && !wantsNoAuth) {
-    throw createDirectiveError("tv serve with --listen requires either `--auth` or `--no-auth`.");
+function parseConfigSetPairs(pairs, invocation) {
+  const keyList = CONFIG_KEYS2.join(", ");
+  if (pairs.length === 0) {
+    throw createDirectiveError(`${invocation} requires at least one <key> <value> pair. Keys: ${keyList}.`);
+  }
+  if (pairs.length % 2 !== 0) {
+    throw createDirectiveError(`${invocation} requires a value for ${formatArgvToken(pairs[pairs.length - 1])}.`);
+  }
+  const keys = [];
+  const changes = {};
+  for (let index = 0; index < pairs.length; index += 2) {
+    const key = pairs[index];
+    const value = pairs[index + 1];
+    if (!CONFIG_KEYS2.includes(key)) {
+      throw createDirectiveError(`${invocation} does not support config key ${formatArgvToken(key)}. Keys: ${keyList}.`);
+    }
+    if (keys.includes(key)) {
+      throw createDirectiveError(`${invocation} sets ${key} more than once.`);
+    }
+    keys.push(key);
+    if (key === "port") {
+      const port = parseWholePort(value, 0);
+      if (port === void 0) {
+        throw createDirectiveError(`${invocation} received an invalid port value ${formatArgvToken(value)}: use a whole decimal integer from 0 through ${MAX_PORT2}.`);
+      }
+      changes.port = port;
+    } else if (key === "listen") {
+      changes.listen = value.split(",").map((address) => address.trim()).filter((address) => address.length > 0);
+    } else if (key === "auth") {
+      if (value !== "true" && value !== "false") {
+        throw createDirectiveError(`${invocation} received an invalid auth value ${formatArgvToken(value)}: use true or false.`);
+      }
+      changes.auth = value === "true";
+    } else {
+      changes.installedByAgent = value;
+    }
   }
-  if (wantsAuth) return true;
-  if (wantsNoAuth) return false;
-  return void 0;
+  return { keys, changes };
 }
 function resolveStaticDir() {
   if (process.argv[1]) {
@@ -57031,29 +57247,22 @@ function formatCommanderError(argv, error48) {
   }
   return null;
 }
-function readAuthToken(storagePath) {
-  const tokenPath = import_node_path20.default.join(storagePath, "state", "token");
+function readAuthToken(home) {
+  const tokenPath = import_node_path20.default.join(home, "state", "token");
   if (!(0, import_node_fs18.existsSync)(tokenPath)) {
     return void 0;
   }
   const token = (0, import_node_fs18.readFileSync)(tokenPath, "utf8").trim();
   return token.length > 0 ? token : void 0;
 }
-function readOrCreateAuthToken(storagePath) {
+function readOrCreateAuthToken(home) {
   return new ServerStore({
-    storagePath,
+    storagePath: home,
     installOnboardingChannels: false
   }).authToken;
 }
-function buildDaemonServeArgs(options = {}) {
-  const args = [process.argv[1] ?? "tv", "serve"];
-  for (const address of options.listen ?? []) args.push("--listen", address);
-  if (options.auth === true) args.push("--auth");
-  if (options.auth === false) args.push("--no-auth");
-  if (options.port !== void 0) args.push("--port", String(options.port));
-  if (options.storagePath) args.push("--storage-path", options.storagePath);
-  if (options.installedByAgent) args.push("--installed-by-agent", options.installedByAgent);
-  return args;
+function buildDaemonServeArgs(home) {
+  return [process.argv[1] ?? "tv", "--home", home, "serve"];
 }
 function redactSensitiveEnv(env) {
   const redacted = {};
@@ -57079,7 +57288,7 @@ function createEnvironment(environment) {
       // resolved content root when one resolved
       // (specs/arch/cli/index.md, build and packaged asset layout).
       store: new ServerStore({
-        storagePath: options.storagePath ?? getTelevisionStoragePath(),
+        storagePath: options.home,
         ...options.bundledViewsPath ? { bundledViewsPath: options.bundledViewsPath } : {},
         ...options.onboardingContentPath ? { onboardingContentPath: options.onboardingContentPath } : {},
         ...options.bundledThemesPath ? { bundledThemesPath: options.bundledThemesPath } : {},
@@ -57087,17 +57296,18 @@ function createEnvironment(environment) {
       }),
       listen: options.listen,
       port: options.port,
+      // Always explicit: the Server constructor's own default is tokenless.
       auth: options.auth,
       staticDir: options.staticDir,
       canonicalDir: options.canonicalDir,
       acpProfile: options.acpProfile,
       telemetry: {
-        launchMode: options.launchMode ?? "cli",
+        launchMode: options.launchMode,
         installedByAgent: options.installedByAgent ?? null
       }
     })),
-    createDaemon: environment.createDaemon ?? ((options = {}) => {
-      const args = buildDaemonServeArgs(options);
+    createDaemon: environment.createDaemon ?? ((options) => {
+      const args = options ? buildDaemonServeArgs(options.home) : [process.argv[1] ?? "tv", "serve"];
       return new Daemon({
         name: DAEMON_NAME,
         description: "Television server \u2014 virtual display for agents",
@@ -57106,7 +57316,7 @@ function createEnvironment(environment) {
         // the service is how a later Node selection takes effect.
         command: process.execPath,
         args,
-        env: options.env
+        env: options?.env
       });
     }),
     resolveStaticDir: environment.resolveStaticDir ?? (() => resolveStaticDir()),
@@ -57127,160 +57337,163 @@ function createEnvironment(environment) {
     onSignal: environment.onSignal ?? ((signal, handler) => process.on(signal, handler))
   };
 }
-function resolveClientStoragePath(storagePath) {
-  return storagePath ?? getTelevisionStoragePath();
+function startRetiredService(home, definition) {
+  const wroteConfig = !(0, import_node_fs18.existsSync)(import_node_path20.default.join(home, "config.json"));
+  if (wroteConfig) updateTelevisionConfig(home, definition.settings);
+  log(home, RETIRED_SERVICE_RECORD, {
+    wroteConfig,
+    guidance: `Reinstall the service with \`tv serve --persist\`, adding \`--home ${home}\` before \`serve\` unless this is the default home, so it runs from the home and its config file. The administrator guide describes the upgrade and is written for an agent to carry out: ${ADMIN_GUIDE_URL}`
+  });
 }
-function createProgram(env, argv = []) {
+function createProgram(env, invocation = { argv: [] }) {
+  const { argv } = invocation;
   const program2 = new Command();
-  const warnForExplicitPortZero = (port) => {
-    if (port === 0) {
-      writeLine(env.stderr, PORT_ZERO_WARNING);
+  const resolveHome = () => {
+    if (invocation.home !== void 0) return invocation.home;
+    try {
+      invocation.home = resolveTelevisionHome({
+        homeOption: invocation.retiredService?.storagePath ?? program2.opts().home,
+        operatingSystemHomeDir: env.resolveHomeDir(),
+        cwd: process.cwd()
+      });
+    } catch (error48) {
+      throw createDirectiveError(error48 instanceof Error ? error48.message : String(error48));
     }
+    return invocation.home;
   };
-  const createAuthenticatedClient = (options = {}) => {
-    warnForExplicitPortZero(options.port);
-    return env.createClient(
-      buildLocalServerURL(options.port),
-      readAuthToken(resolveClientStoragePath(options.storagePath))
-    );
+  const resolveClientPort = (config2, portOption) => {
+    const enteredInvocation = formatEnteredInvocation(argv);
+    if (config2.settings.port === 0) {
+      if (portOption === void 0) {
+        throw createDirectiveError(
+          `${enteredInvocation} requires --port because ${config2.configPath} sets port 0. Pass the port from the Television server's startup URL.`
+        );
+      }
+      return portOption;
+    }
+    if (portOption !== void 0) {
+      throw createDirectiveError(
+        `${enteredInvocation} does not accept --port because ${config2.configPath} sets port ${config2.settings.port}. Omit --port to use the configured port.`
+      );
+    }
+    return config2.settings.port;
+  };
+  const resolveServerURL = (portOption) => {
+    const port = resolveClientPort(readTelevisionConfig(resolveHome()), portOption);
+    return buildServerURL(DEFAULT_SERVER_HOST, port);
+  };
+  const createAuthenticatedClient = (options) => {
+    const serverURL = resolveServerURL(options.port);
+    return env.createClient(serverURL, readAuthToken(resolveHome()));
   };
   const emitSkillInstallTelemetry = async (input) => {
     await bestEffortWithinTimeout2(env.emitSkillInstalledTelemetry({
-      storagePath: getTelevisionStoragePath(),
+      storagePath: input.home,
       version: telemetryVersion(readCLIVersion()),
       agentType: input.agentType,
       ...input.installedByAgent === void 0 ? {} : { installedByAgent: input.installedByAgent },
       env: process.env
     }), SKILL_INSTALL_TELEMETRY_TIMEOUT_MS2);
   };
-  const uninstallPersistedService = async (storagePath) => {
+  const uninstallPersistedService = async (home) => {
     const daemon = env.createDaemon();
     let outcome = "uninstalled";
     try {
       await daemon.uninstall();
     } catch (error48) {
       outcome = "error";
-      log(storagePath, "persisted service uninstall failed", { daemonName: DAEMON_NAME, outcome, error: error48 });
+      log(home, "persisted service uninstall failed", { daemonName: DAEMON_NAME, outcome, error: error48 });
       throw error48;
     }
-    log(storagePath, "persisted service uninstalled", { daemonName: DAEMON_NAME, outcome });
+    log(home, "persisted service uninstalled", { daemonName: DAEMON_NAME, outcome });
     writeJSON(env.stdout, { status: "stopped" });
   };
-  program2.name("tv").description("Television \u2014 virtual display for agents").version(readCLIVersionOutput(env.resolveHomeDir)).option("-v", "Output the version number").showSuggestionAfterError(false).addHelpText("after", buildAgentHelpNote()).configureOutput({
-    writeOut: (str) => env.stdout.write(str),
-    writeErr: (str) => env.stderr.write(str),
-    outputError: () => {
+  const installPersistedService = async (home, config2) => {
+    const { settings, configPath } = config2;
+    if (settings.port === 0) {
+      throw createDirectiveError(
+        `${formatEnteredInvocation(argv)} requires a stable port, but ${configPath} sets port 0. Choose one with \`tv config set port <number>\`.`
+      );
     }
-  }).exitOverride();
-  program2.command("serve").description("Start the Television server").option("--listen <address>", "Additional IPv4 address to bind to (repeatable or comma-separated)", collectOption, []).option("--auth", "Require bearer-token auth on every listener").option("--no-auth", "Disable bearer-token auth on every listener").option("--port <number>", "Port to listen on", parsePortOption).option("--storage-path <path>", "Directory for persisted channel data").option("--installed-by-agent <agent-runtime-harness-name>", "Agent runtime harness name operating this server").option("--persist", "Install as a persistent system service").option("--persist-uninstall", "Uninstall the persistent system service").action(async (opts) => {
-    if (opts.persist && opts.persistUninstall) {
-      throw createDirectiveError("Use either `--persist` or `--persist-uninstall`, not both.");
+    const profile = resolveACPAgentProfile(process.env);
+    const daemonEnv = buildPersistedACPEnvironment(process.env, { developerHome: env.resolveHomeDir() });
+    daemonEnv[TELEMETRY_LAUNCH_MODE_ENV] = "daemon";
+    if (profile && !isACPCommandResolvable(profile.command, daemonEnv)) {
+      const error48 = createDirectiveError(
+        `Could not find ACP agent command \`${profile.command}\` for \`TELEVISION_ACP_AGENT=${profile.agent}\` on the persisted PATH. Set TELEVISION_ACP_AGENT to \`openclaw\` or \`hermes\`, and ensure the selected agent binary is available on PATH before running \`tv serve --persist\`.`
+      );
+      log(home, "server startup refused before binding", { argv, error: error48 });
+      throw error48;
     }
-    const storagePathForLogs = opts.storagePath ?? getTelevisionStoragePath();
-    if (opts.persistUninstall) {
-      await uninstallPersistedService(storagePathForLogs);
-      return;
+    const token = settings.auth ? readOrCreateAuthToken(home) : null;
+    const daemonOptions = { home, env: daemonEnv };
+    const execStart = [process.execPath, ...buildDaemonServeArgs(home)];
+    const daemon = env.createDaemon(daemonOptions);
+    const daemonStatus = await daemon.status();
+    if (daemonStatus.installed || daemonStatus.running) {
+      await daemon.uninstall();
     }
-    let auth;
     try {
-      auth = resolveServeAuth(argv, opts.listen.length > 0);
-      resolveBindAddresses(opts.listen);
+      await daemon.install();
+      log(home, "persisted service installed", {
+        daemonName: DAEMON_NAME,
+        execStart,
+        env: redactSensitiveEnv(daemonEnv),
+        replacedExisting: daemonStatus.installed || daemonStatus.running,
+        outcome: "installed"
+      });
     } catch (error48) {
-      log(storagePathForLogs, "server startup refused before binding", { argv, error: error48 });
-      throw error48;
-    }
-    if (opts.persist) {
-      if (opts.port === 0) {
-        throw createDirectiveError(
-          "tv serve --persist --port 0 requires a stable port; port 0 lets the operating system choose a runtime port and cannot produce a stable persisted-service startup URL. Set TELEVISION_PORT to a stable port or pass a non-zero --port."
-        );
-      }
-      const clientPort = resolveClientPort(opts.port);
-      const storagePath = import_node_path20.default.resolve(opts.storagePath ?? getTelevisionStoragePath());
-      const profile2 = resolveACPAgentProfile(process.env);
-      const daemonEnv = buildPersistedACPEnvironment(process.env, { developerHome: env.resolveHomeDir() });
-      if (process.env.TELEVISION_PORT !== void 0 && process.env.TELEVISION_PORT !== "") {
-        daemonEnv.TELEVISION_PORT = process.env.TELEVISION_PORT;
-      }
-      if (process.env.TELEVISION_STORAGE_PATH !== void 0 && process.env.TELEVISION_STORAGE_PATH !== "") {
-        daemonEnv.TELEVISION_STORAGE_PATH = process.env.TELEVISION_STORAGE_PATH;
-      }
-      daemonEnv[TELEMETRY_LAUNCH_MODE_ENV] = "daemon";
-      if (profile2 && !isACPCommandResolvable(profile2.command, daemonEnv)) {
-        const error48 = createDirectiveError(
-          `Could not find ACP agent command \`${profile2.command}\` for \`TELEVISION_ACP_AGENT=${profile2.agent}\` on the persisted PATH. Set TELEVISION_ACP_AGENT to \`openclaw\` or \`hermes\`, and ensure the selected agent binary is available on PATH before running \`tv serve --persist\`.`
-        );
-        log(storagePath, "server startup refused before binding", { argv, error: error48 });
-        throw error48;
-      }
-      const daemonOptions = {
-        listen: opts.listen,
-        auth,
-        port: opts.port,
-        storagePath,
-        ...opts.installedByAgent === void 0 ? {} : { installedByAgent: opts.installedByAgent },
-        env: daemonEnv
-      };
-      const daemon = env.createDaemon(daemonOptions);
-      const daemonStatus = await daemon.status();
-      if (daemonStatus.installed || daemonStatus.running) {
-        await daemon.uninstall();
-      }
-      try {
-        await daemon.install();
-        log(storagePath, "persisted service installed", {
-          daemonName: DAEMON_NAME,
-          execStart: [process.execPath, ...buildDaemonServeArgs(daemonOptions)],
-          env: redactSensitiveEnv(daemonEnv),
-          replacedExisting: daemonStatus.installed || daemonStatus.running,
-          outcome: "installed"
-        });
-      } catch (error48) {
-        log(storagePath, "persisted service install failed", {
-          daemonName: DAEMON_NAME,
-          execStart: [process.execPath, ...buildDaemonServeArgs(daemonOptions)],
-          env: redactSensitiveEnv(daemonEnv),
-          outcome: "error",
-          error: error48
-        });
-        throw error48;
-      }
-      const serverURLs2 = resolveBindAddresses(opts.listen).map((address) => buildServerURL(address, clientPort));
-      writeConnectURLs(env.stdout, serverURLs2, {
-        installed: true,
-        token: auth === true ? readOrCreateAuthToken(storagePath) : null
+      log(home, "persisted service install failed", {
+        daemonName: DAEMON_NAME,
+        execStart,
+        env: redactSensitiveEnv(daemonEnv),
+        outcome: "error",
+        error: error48
       });
-      return;
+      throw error48;
     }
-    warnForExplicitPortZero(opts.port);
+    const serverURLs = resolveBindAddresses(settings.listen).map((address) => buildServerURL(address, settings.port));
+    writeConnectURLs(env.stdout, serverURLs, { installed: true, token });
+  };
+  const serveInForeground = async (home, settings) => {
     const profile = resolveACPAgentProfile(process.env);
     if (profile && !isACPCommandResolvable(profile.command, process.env)) {
       const error48 = createDirectiveError(
         `Could not find ACP agent command \`${profile.command}\` for \`TELEVISION_ACP_AGENT=${profile.agent}\` on PATH. Set TELEVISION_ACP_AGENT to \`openclaw\` or \`hermes\`, and ensure the selected agent binary is available on PATH before running \`tv serve\`.`
       );
-      log(storagePathForLogs, "server startup refused before binding", { argv, error: error48 });
+      log(home, "server startup refused before binding", { argv, error: error48 });
       throw error48;
     }
+    if (settings.port === 0) {
+      writeLine(env.stderr, PORT_ZERO_WARNING);
+    }
     const onboardingContentPath = env.resolveOnboardingContentPath();
     const bundledThemesPath = env.resolveBundledThemesPath();
     const server = env.createServer({
-      listen: opts.listen,
-      auth,
-      port: resolveClientPort(opts.port),
-      storagePath: opts.storagePath,
+      home,
+      listen: settings.listen,
+      port: settings.port,
+      auth: settings.auth,
+      ...settings.installedByAgent === void 0 ? {} : { installedByAgent: settings.installedByAgent },
       staticDir: env.resolveStaticDir(),
       canonicalDir: env.resolveCanonicalDir(),
       bundledViewsPath: env.resolveBundledViewsPath(),
       ...onboardingContentPath !== void 0 ? { onboardingContentPath } : {},
       ...bundledThemesPath !== void 0 ? { bundledThemesPath } : {},
       launchMode: resolveTelemetryLaunchMode(process.env),
-      ...opts.installedByAgent === void 0 ? {} : { installedByAgent: opts.installedByAgent },
       ...profile ? { acpProfile: profile } : {}
     });
     await server.start();
+    if (!settings.auth) {
+      writeLine(env.stderr, TOKENLESS_WARNING);
+      const nonLoopbackAddresses = resolveBindAddresses(settings.listen).filter((address) => address !== LOOPBACK_IPV4);
+      if (nonLoopbackAddresses.length > 0) {
+        writeLine(env.stderr, `Non-loopback listeners without auth: ${nonLoopbackAddresses.join(", ")}`);
+      }
+    }
     const serverURLs = server.getBaseURLs?.() ?? [server.getBaseURL()];
     writeConnectURLs(env.stdout, serverURLs, {
-      token: auth === true ? server.getAuthToken() : null
+      token: settings.auth ? server.getAuthToken() : null
     });
     await new Promise((resolve, reject) => {
       let shuttingDown = false;
@@ -57301,10 +57514,61 @@ function createProgram(env, argv = []) {
         void shutdown("SIGTERM");
       });
     });
+  };
+  const versionOutput = readCLIVersionOutput(env.resolveHomeDir);
+  program2.name("tv").description("Television \u2014 virtual display for agents").version(versionOutput).option("-v", "Output the version number").option("--home <path>", "Television home directory (default: the path in ~/.tv-home, otherwise ~/.television)").showSuggestionAfterError(false).addHelpText("after", buildAgentHelpNote()).configureOutput({
+    writeOut: (str) => env.stdout.write(str),
+    writeErr: (str) => env.stderr.write(str),
+    outputError: () => {
+    }
+  }).exitOverride();
+  program2.on("option:v", () => {
+    env.stdout.write(`${versionOutput}
+`);
+    throw new CommanderError(0, "commander.version", versionOutput);
+  });
+  program2.command("serve").description("Start the Television server with the selected home's settings").option("--persist", "Install as a persistent system service").option("--persist-uninstall", "Uninstall the persistent system service").action(async (opts) => {
+    if (opts.persist && opts.persistUninstall) {
+      throw createDirectiveError("Use either `--persist` or `--persist-uninstall`, not both.");
+    }
+    const home = resolveHome();
+    if (opts.persistUninstall) {
+      await uninstallPersistedService(home);
+      return;
+    }
+    let config2;
+    try {
+      if (invocation.retiredService) startRetiredService(home, invocation.retiredService);
+      config2 = readTelevisionConfig(home);
+    } catch (error48) {
+      log(home, "server startup refused before binding", { argv, error: error48 });
+      throw error48;
+    }
+    if (opts.persist) {
+      await installPersistedService(home, config2);
+      return;
+    }
+    await serveInForeground(home, config2.settings);
+  });
+  const configCommand = program2.command("config").description("Show the effective settings of the selected home, or change settings in its config file");
+  configCommand.command("set").description("Change settings in the selected home's config file").argument("[pairs...]", `<key> <value> pairs; keys: ${CONFIG_KEYS2.join(", ")}`).action((pairs) => {
+    const { keys, changes } = parseConfigSetPairs(pairs, formatEnteredInvocation(argv));
+    const config2 = updateTelevisionConfig(resolveHome(), changes);
+    writeLine(env.stdout, `Updated ${config2.configPath}: ${keys.join(", ")}.`);
+    writeLine(env.stdout, "Restart foreground `tv serve`, or rerun `tv serve --persist`, for a running server to use the new settings.");
+  });
+  configCommand.command("show").description("Print the selected home, its config file, and the effective settings as JSON").action(() => {
+    const config2 = readTelevisionConfig(resolveHome());
+    writeJSON(env.stdout, {
+      home: config2.home,
+      configPath: config2.configPath,
+      configFileExists: config2.configFileExists,
+      settings: { ...config2.settings, installedByAgent: config2.settings.installedByAgent ?? null }
+    });
   });
   program2.command("create-path-artifact").description(
     "Create a path artifact that points at an existing absolute markdown or HTML file, or at a directory with a root index.html/index.htm (trailing separator optional; the server detects file vs directory on disk). Television records the pointer only; HTML and directory targets are read-only, and markdown targets are written through only by in-UI editor saves via PUT /markdown/<id>."
-  ).requiredOption("--channel <id>", "Target channel ID").requiredOption("--title <title>", "Artifact title").requiredOption("--path <path>", "Absolute path to an existing markdown/HTML file or indexed directory (trailing separator optional)").option("--focus-artifact", "Focus the new artifact after creation").option("--no-focus", "Create the artifact in the background without changing focus").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
+  ).requiredOption("--channel <id>", "Target channel ID").requiredOption("--title <title>", "Artifact title").requiredOption("--path <path>", "Absolute path to an existing markdown/HTML file or indexed directory (trailing separator optional)").option("--focus-artifact", "Focus the new artifact after creation").option("--no-focus", "Create the artifact in the background without changing focus").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
     const shouldFocus = resolveFocusDirective(argv, "create-path-artifact", "--focus-artifact");
     const artifactPath = opts.path.trim();
     const client = createAuthenticatedClient(opts);
@@ -57322,7 +57586,7 @@ function createProgram(env, argv = []) {
   });
   program2.command("create-url-artifact").description(
     "Create a URL artifact that points at an absolute http(s) URL. Television records the pointer only and does not own or modify the remote page."
-  ).requiredOption("--channel <id>", "Target channel ID").requiredOption("--title <title>", "Artifact title").requiredOption("--url <url>", "http(s) URL").option("--focus-artifact", "Focus the new artifact after creation").option("--no-focus", "Create the artifact in the background without changing focus").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
+  ).requiredOption("--channel <id>", "Target channel ID").requiredOption("--title <title>", "Artifact title").requiredOption("--url <url>", "http(s) URL").option("--focus-artifact", "Focus the new artifact after creation").option("--no-focus", "Create the artifact in the background without changing focus").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).addHelpText("after", buildArtifactWorkflowHelpNote(true)).action(async (opts) => {
     const shouldFocus = resolveFocusDirective(argv, "create-url-artifact", "--focus-artifact");
     const artifactURL = opts.url.trim();
     const client = createAuthenticatedClient(opts);
@@ -57338,12 +57602,9 @@ function createProgram(env, argv = []) {
     writeLine(env.stdout, `URL artifact ${artifact.id} created.`);
     writeLine(env.stdout, `Television registered ${artifactURL}.`);
   });
-  program2.command("storage-path").description("Print the Television storage path").action(() => {
-    writeJSON(env.stdout, { storagePath: getTelevisionStoragePath() });
-  });
   program2.command("update-artifact").description(
     "Update artifact metadata in place: --title on any artifact, --path to repoint a path artifact, --url to repoint a URL artifact. ID and kind are immutable. The server validates the new pointer; for path artifacts the target must exist (trailing separator optional) and the content watcher follows it."
-  ).requiredOption("--id <id>", "Artifact ID").option("--title <title>", "New title").option("--path <path>", "New absolute path for a path artifact: markdown/HTML file or indexed directory (trailing separator optional)").option("--url <url>", "New http(s) URL for a URL artifact").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  ).requiredOption("--id <id>", "Artifact ID").option("--title <title>", "New title").option("--path <path>", "New absolute path for a path artifact: markdown/HTML file or indexed directory (trailing separator optional)").option("--url <url>", "New http(s) URL for a URL artifact").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     if (opts.title === void 0 && opts.path === void 0 && opts.url === void 0) {
       throw createDirectiveError("tv update-artifact requires at least one of --title, --path, or --url.");
     }
@@ -57361,20 +57622,20 @@ function createProgram(env, argv = []) {
   });
   program2.command("delete-artifact").description(
     "Delete an artifact registry record, remove its card from its owning channel, and delete its metadata. Television never removes or mutates the pointed-to path or URL."
-  ).requiredOption("--id <id>", "Artifact ID").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  ).requiredOption("--id <id>", "Artifact ID").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const client = createAuthenticatedClient(opts);
     const result = await client.artifacts.delete({ artifactID: opts.id });
     for (const line of formatDeleteArtifactResult(result)) {
       writeLine(env.stdout, line);
     }
   });
-  program2.command("get-artifact").description("Fetch an artifact's metadata as JSON").requiredOption("--id <id>", "Artifact ID").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  program2.command("get-artifact").description("Fetch an artifact's metadata as JSON").requiredOption("--id <id>", "Artifact ID").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const client = createAuthenticatedClient(opts);
     writeJSON(env.stdout, await client.artifacts.get({ artifactID: opts.id }));
   });
   program2.command("list-artifacts").description(
     "List artifacts as JSON. With no filter, every artifact is returned. --channel <id> filters to artifacts on that channel."
-  ).option("--channel <id>", "Filter to artifacts on this channel").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  ).option("--channel <id>", "Filter to artifacts on this channel").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const client = createAuthenticatedClient(opts);
     const filter = {};
     if (opts.channel !== void 0) filter.channelID = opts.channel;
@@ -57382,7 +57643,7 @@ function createProgram(env, argv = []) {
   });
   program2.command("create-channel").description(
     "Create a new channel. Pick --focus-channel when the user should be taken to the new channel immediately (creating a workspace they're about to use), or --no-focus to create it in the background without disturbing their current view. A new channel starts empty; create new path or URL artifacts on it with the create-*-artifact commands using --channel."
-  ).requiredOption("--name <name>", "Channel name").option("--focus-channel", "Focus the new channel after creating it").option("--no-focus", "Create the channel in the background without changing focus").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  ).requiredOption("--name <name>", "Channel name").option("--focus-channel", "Focus the new channel after creating it").option("--no-focus", "Create the channel in the background without changing focus").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const shouldFocus = resolveFocusDirective(argv, "create-channel", "--focus-channel");
     const client = createAuthenticatedClient(opts);
     const { channel } = await client.channels.create({ name: opts.name });
@@ -57391,7 +57652,7 @@ function createProgram(env, argv = []) {
     }
     writeLine(env.stdout, `Channel created: ${channel.id} (${channel.name})`);
   });
-  program2.command("update-channel").description("Rename a channel in place").requiredOption("--channel <id>", "Channel ID").requiredOption("--name <name>", "New channel name").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  program2.command("update-channel").description("Rename a channel in place").requiredOption("--channel <id>", "Channel ID").requiredOption("--name <name>", "New channel name").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const client = createAuthenticatedClient(opts);
     const { channel } = await client.channels.update({
       channelID: opts.channel,
@@ -57401,26 +57662,26 @@ function createProgram(env, argv = []) {
   });
   program2.command("remove-channel").description(
     "Delete a channel. Artifacts on the channel are permanently deleted from the Television registry; their pointed-to path or URL targets are not touched."
-  ).requiredOption("--channel <id>", "Channel ID").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  ).requiredOption("--channel <id>", "Channel ID").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const client = createAuthenticatedClient(opts);
     const result = await client.channels.remove({ channelID: opts.channel });
     for (const line of formatChannelRemovalResult(result)) {
       writeLine(env.stdout, line);
     }
   });
-  program2.command("list-channels").description("List all channels").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  program2.command("list-channels").description("List all channels").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const client = createAuthenticatedClient(opts);
     writeJSON(env.stdout, await client.channels.list());
   });
   program2.command("get-channel").description(
     "Get a channel and its path/url artifact records as JSON. With no --channel, auto-selects when exactly one channel exists; otherwise --channel is required."
-  ).option("--channel <id>", "Channel ID (auto-selects if only one exists)").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  ).option("--channel <id>", "Channel ID (auto-selects if only one exists)").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const client = createAuthenticatedClient(opts);
     writeJSON(env.stdout, await client.channels.get({ channelID: opts.channel }));
   });
   program2.command("focus-status").description(
     "Print display state as JSON: the active (persistently focused) channel ID and the active theme ID."
-  ).option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  ).option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const client = createAuthenticatedClient(opts);
     const display = await client.display.get();
     writeJSON(env.stdout, {
@@ -57431,14 +57692,14 @@ function createProgram(env, argv = []) {
   });
   program2.command("focus-channel").description(
     "Set persistent channel focus. The change is broadcast to every connected GUI client and survives reconnects. This is the right command when the user wants to switch to a different channel and stay there. For just nudging attention to a specific artifact (which may live on the current channel), prefer `tv focus-artifact`."
-  ).requiredOption("--channel <id>", "Channel ID").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  ).requiredOption("--channel <id>", "Channel ID").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const client = createAuthenticatedClient(opts);
     await client.display.patch({ focusedChannelId: opts.channel });
     writeLine(env.stdout, `Focused channel ${opts.channel}.`);
   });
   program2.command("set-theme").description(
     "Activate an installed display theme by its exact theme ID, or use `none` to run without a theme."
-  ).argument("<theme>", "Exact theme ID to activate, or `none` to use no theme").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").addHelpText("after", [
+  ).argument("<theme>", "Exact theme ID to activate, or `none` to use no theme").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).addHelpText("after", [
     "",
     "Examples:",
     "  tv set-theme paperlike    Activate the `paperlike` theme.",
@@ -57476,9 +57737,12 @@ function createProgram(env, argv = []) {
     }
     writeLine(env.stdout, `Active theme changed from '${previousLabel}' to '${nextLabel}'.`);
   });
+  program2.command("themes-path").description("Print the themes directory of the selected home as JSON").action(() => {
+    writeJSON(env.stdout, { themesPath: import_node_path20.default.join(resolveHome(), "themes") });
+  });
   program2.command("focus-artifact").description(
     "Send a transient focus nudge for a specific artifact. Connected clients select the artifact's tab page and switch to its channel when needed. This is NOT persisted as state \u2014 there is no concept of a 'focused artifact' that survives reconnects (the focused channel is persistent, but artifact focus is a one-shot event)."
-  ).requiredOption("--id <id>", "Artifact ID").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  ).requiredOption("--id <id>", "Artifact ID").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const client = createAuthenticatedClient(opts);
     const result = await client.display.focus({ artifactID: opts.id });
     writeLine(env.stdout, `Focused artifact ${result.artifactID} on channel ${result.channelID}.`);
@@ -57491,6 +57755,7 @@ function createProgram(env, argv = []) {
     "`tv skills install -i` runs the external skills installer against Television's bundled skills root."
   ].join("\n"));
   skillsCommand.command("install").description("Copy bundled Television skills into an agent harness skills folder, or run the external installer against the bundled skills root").argument("[path]", "Destination agent skills folder (for example: ~/.openclaw/skills, ~/.hermes/skills, ~/.agents/skills)").option("-i, --interactive", "Run the external skills installer against the bundled Television skills root").option("--installed-by-agent <agent-runtime-harness-name>", "Agent runtime harness name performing this install").action(async function(inputPath, opts) {
+    const home = resolveHome();
     const bundledTelevisionSkillsCollectionRoot = env.resolveBundledSkillsRoot();
     if (opts.interactive) {
       if (inputPath) {
@@ -57502,6 +57767,7 @@ function createProgram(env, argv = []) {
       const args = ["add", bundledTelevisionSkillsCollectionRoot];
       await env.runSkillsInstaller(args);
       await emitSkillInstallTelemetry({
+        home,
         agentType: "interactive-install",
         ...opts.installedByAgent === void 0 ? {} : { installedByAgent: opts.installedByAgent }
       });
@@ -57524,30 +57790,33 @@ function createProgram(env, argv = []) {
       writeLine(env.stdout, `  to:   ${skill.destinationPath}`);
     }
     await emitSkillInstallTelemetry({
+      home,
       agentType: deriveAgentTypeFromPath(destinationRoot).agent_type,
       ...opts.installedByAgent === void 0 ? {} : { installedByAgent: opts.installedByAgent }
     });
   });
   const telemetryCommand = program2.command("telemetry").description("Control telemetry for the running Television server");
-  telemetryCommand.command("disable").description("Disable telemetry for the running Television server").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  telemetryCommand.command("disable").description("Disable telemetry for the running Television server").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const client = createAuthenticatedClient(opts);
     writeJSON(env.stdout, await client.telemetry.disable());
   });
-  telemetryCommand.command("enable").description("Enable telemetry for the running Television server").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
+  telemetryCommand.command("enable").description("Enable telemetry for the running Television server").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
     const client = createAuthenticatedClient(opts);
     writeJSON(env.stdout, await client.telemetry.enable());
   });
   program2.command("stop").description("Stop the Television system service").action(async () => {
-    await uninstallPersistedService(getTelevisionStoragePath());
+    await uninstallPersistedService(resolveHome());
   });
-  program2.command("status").description("Check Television server and service status").option("--port <number>", "Server port", parsePortOption).option("--storage-path <path>", "Directory containing the Television token").action(async (opts) => {
-    const serverURL = buildLocalServerURL(opts.port);
+  program2.command("status").description("Print the selected home, server health, version, telemetry state, and service status as JSON").option("--port <number>", "Server port; required when the config file sets port 0", parseClientPortOption).action(async (opts) => {
+    const home = resolveHome();
+    const serverURL = resolveServerURL(opts.port);
     const result = {
+      home,
       serverURL,
       healthy: false
     };
     try {
-      const client = createAuthenticatedClient(opts);
+      const client = env.createClient(serverURL, readAuthToken(home));
       const health = await client.health();
       result.healthy = true;
       if (health.version !== void 0) result.version = health.version;
@@ -57572,17 +57841,25 @@ function listVisibleCLICommandNames() {
 }
 async function runCLI(argv, environment = {}) {
   const env = createEnvironment(environment);
+  const { command, retired, remaining } = extractRetiredOptions(argv);
+  const retiredService = retired.length > 0 ? readRetiredServiceDefinition(command, retired, remaining, process.env) : void 0;
+  if (retired.length > 0 && !retiredService) {
+    const named = [...new Set(retired.map((option) => option.name))].join(", ");
+    env.stderr.write(`${ensureHelpPointer(`This version of Television does not accept ${named}. ${RETIRED_OPTIONS_GUIDANCE}`)}
+`);
+    return 1;
+  }
+  if (process.env[TELEMETRY_LAUNCH_MODE_ENV] !== "daemon" && (process.env.TELEVISION_PORT || process.env.TELEVISION_STORAGE_PATH)) {
+    writeLine(env.stderr, LEGACY_VARIABLES_WARNING);
+  }
+  const invocation = { argv, ...retiredService ? { retiredService } : {} };
   try {
-    if (argv.length === 1 && argv[0] === "-v") {
-      writeLine(env.stdout, readCLIVersionOutput(env.resolveHomeDir));
-      return 0;
-    }
-    const program2 = createProgram(env, argv);
+    const program2 = createProgram(env, invocation);
     if (argv.length === 0) {
       program2.outputHelp();
       return 0;
     }
-    await program2.parseAsync(argv, { from: "user" });
+    await program2.parseAsync(remaining, { from: "user" });
     return 0;
   } catch (error48) {
     if (error48 instanceof Error && "exitCode" in error48) {
@@ -57596,7 +57873,7 @@ async function runCLI(argv, environment = {}) {
       }
       return 1;
     }
-    env.stderr.write(`${formatCLIError(error48, argv)}
+    env.stderr.write(`${formatCLIError(error48, invocation)}
 `);
     return exitStatusFromError(error48) ?? 1;
   }