home-hosted 0.3.0 → 0.4.0

package/dist/cli.js

@@ -88,7 +88,7 @@ function parseBind(value) {
 	const parsed = bindSchema(value);
 	return parsed instanceof type.errors ? null : parsed;
 }
-var bindSchema, portSchema, restartSchema, httpCheckSchema, resourcesSchema, healthSchema, stopSchema, bootstrapSchema, bootstrapOrNullSchema, logBufferLinesSchema, serverSchema, authSchema, telegramSchema, notificationsSchema, logsSchema, tlsSchema, hostSchema, backupsSchema, controlSchema, defaultsSchema, restartPatchSchema, httpCheckPatchSchema, resourcesPatchSchema, healthPatchSchema, stopPatchSchema, authPatchSchema, telegramPatchSchema, notificationsPatchSchema, hostPatchSchema, backupsPatchSchema, logsPatchSchema, tlsPatchSchema, controlPatchSchema, defaultsPatchSchema, editableFields, serverPatchSchema, serverCreateSchema, settingsPatchSchema, authStatusSchema, tlsStatusSchema, telegramStatusSchema, notificationViewSchema, sessionViewSchema, loginSchema, passwordValueSchema, passwordSchema, serverStatusSchema, healthStateSchema, portStateSchema, logStreamSchema, logLineSchema, historyEventSchema, serverHistorySchema, processResourcesSchema, hostDiskSchema, hostViewSchema, backupFileSchema, backupPathSchema, backupsViewSchema, restoreItemSchema, restorePlanSchema, backupCreateSchema, restoreRequestSchema, serverViewSchema, controlViewSchema, appStateSchema, logQuerySchema, logHistoryQuerySchema, logFileInfoSchema, logServerViewSchema, logServersViewSchema, notificationActionSchema, telegramTokenSchema, apiErrorSchema, uiMetaSchema, tlsUploadSchema;
+var bindSchema, portSchema, restartSchema, httpCheckSchema, resourcesSchema, healthSchema, stopSchema, bootstrapSchema, bootstrapOrNullSchema, logBufferLinesSchema, serverSchema, authSchema, telegramSchema, notificationsSchema, logsSchema, tlsSchema, hostSchema, backupsSchema, controlSchema, defaultsSchema, restartPatchSchema, httpCheckPatchSchema, resourcesPatchSchema, healthPatchSchema, stopPatchSchema, authPatchSchema, telegramPatchSchema, notificationsPatchSchema, hostPatchSchema, backupsPatchSchema, logsPatchSchema, tlsPatchSchema, controlPatchSchema, defaultsPatchSchema, editableFields, serverPatchSchema, serverCreateSchema, settingsPatchSchema, authStatusSchema, tlsStatusSchema, telegramStatusSchema, notificationViewSchema, sessionViewSchema, loginSchema, passwordValueSchema, passwordSchema, serverStatusSchema, healthStateSchema, portStateSchema, logStreamSchema, logLineSchema, historyEventSchema, serverHistorySchema, processResourcesSchema, hostDiskSchema, hostViewSchema, backupFileSchema, backupPathSchema, backupsViewSchema, restoreItemSchema, restorePlanSchema, backupCreateSchema, restoreRequestSchema, serverViewSchema, controlViewSchema, appStateSchema, logQuerySchema, freePortResultSchema, logHistoryQuerySchema, logFileInfoSchema, logServerViewSchema, logServersViewSchema, notificationActionSchema, telegramTokenSchema, apiErrorSchema, uiMetaSchema, tlsUploadSchema;
 var init_contracts = __esmMin((() => {
 	bindSchema = type("\"local\" | \"lan\" | /^\\d{1,3}(?:\\.\\d{1,3}){3}$/");
 	portSchema = type("1 <= number.integer <= 65535 | null");
@@ -162,7 +162,7 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		bootstrap: bootstrapOrNullSchema.optional(),
 		port: portSchema.optional(),
 		bind: bindSchema.default(() => "local"),
-		onPortConflict: "\"block\" | \"warn\" = \"block\"",
+		onPortConflict: "\"block\" | \"warn\" | \"follow\" | \"reclaim\" = \"block\"",
 		restart: restartSchema.default(() => ({})),
 		health: healthSchema.default(() => ({})),
 		stop: stopSchema.default(() => ({})),
@@ -226,7 +226,7 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 	}).onUndeclaredKey("reject");
 	controlSchema = type({
 		/** What the panel calls itself; the stock UI shows it in the sidebar. */
-		label: "1 <= string <= 60 = \"Stock UI\"",
+		label: "1 <= string <= 60 = \"home-hosted\"",
 		port: "1 <= number.integer <= 65535 = 3999",
 		/** Where the control panel itself listens; keep it `local` unless you mean it. */
 		host: bindSchema.default(() => "local"),
@@ -238,7 +238,7 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		enabled: "boolean = true",
 		autostart: "boolean = false",
 		bind: bindSchema.default(() => "local"),
-		onPortConflict: "\"block\" | \"warn\" = \"block\"",
+		onPortConflict: "\"block\" | \"warn\" | \"follow\" | \"reclaim\" = \"block\"",
 		restart: restartSchema.default(() => ({})),
 		health: healthSchema.default(() => ({})),
 		stop: stopSchema.default(() => ({})),
@@ -329,7 +329,7 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		enabled: "boolean?",
 		autostart: "boolean?",
 		bind: bindSchema.optional(),
-		onPortConflict: "\"block\" | \"warn\"?",
+		onPortConflict: "\"block\" | \"warn\" | \"follow\" | \"reclaim\"?",
 		restart: restartPatchSchema.optional(),
 		health: healthPatchSchema.optional(),
 		stop: stopPatchSchema.optional(),
@@ -347,7 +347,7 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		bootstrap: bootstrapOrNullSchema.optional(),
 		port: portSchema.optional(),
 		bind: bindSchema.optional(),
-		onPortConflict: "\"block\" | \"warn\"?",
+		onPortConflict: "\"block\" | \"warn\" | \"follow\" | \"reclaim\"?",
 		restart: restartPatchSchema.optional(),
 		health: healthPatchSchema.optional(),
 		stop: stopPatchSchema.optional(),
@@ -375,6 +375,13 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		enabled: "boolean",
 		passwordSet: "boolean",
 		passwordUpdatedAt: "number | null",
+		/**
+		* An API token is set; it is shown here as a flag, never as a value. Optional so
+		* a freshly built UI still parses the state of a panel process that predates it:
+		* an upgrade replaces `uis/stock/dist` on disk while the old process keeps
+		* serving, and a missing key must not blank the whole app.
+		*/
+		apiTokenSet: "boolean?",
 		/** Still the boot-time default; the login page says so and exposure stays blocked. */
 		usingDefaultPassword: "boolean",
 		/** The panel currently listens beyond loopback. */
@@ -419,6 +426,8 @@ maxRssBytes: "number.integer >= 0 = 0" }).onUndeclaredKey("reject");
 		authenticated: "boolean",
 		authRequired: "boolean",
 		passwordSet: "boolean",
+		/** A long-lived API token is configured; optional for the same reason as above. */
+		apiTokenSet: "boolean?",
 		usingDefaultPassword: "boolean",
 		/** The boot-time password, exposed only while it is still in use. */
 		defaultPassword: "string | null",
@@ -553,6 +562,8 @@ password: passwordValueSchema.optional() }).onUndeclaredKey("reject");
 		health: healthStateSchema,
 		portState: portStateSchema,
 		pid: "number | null",
+		/** True when the process serving this entry was adopted, not spawned by the panel. */
+		adopted: "boolean?",
 		startedAt: "number | null",
 		exitCode: "number | null",
 		exitSignal: "string | null",
@@ -608,6 +619,17 @@ password: passwordValueSchema.optional() }).onUndeclaredKey("reject");
 		lines: logLineSchema.array().optional()
 	});
 	logQuerySchema = type({ limit: "string?" });
+	freePortResultSchema = type({
+		ok: "boolean",
+		port: "number | null",
+		/** Asked to leave with SIGTERM, and the ones that ignored it. */
+		terminated: "number[]",
+		forced: "number[]",
+		/** Listeners this panel supervises; never signalled. */
+		skipped: "number[]",
+		/** The port answers no more after the attempt. */
+		free: "boolean"
+	});
 	logHistoryQuerySchema = type({
 		tail: "string?",
 		/** Case-insensitive substring filter over the tail window. */
@@ -735,6 +757,7 @@ function isLoopbackRequest(c) {
 var init_loopback = __esmMin((() => {}));
 //#endregion
 //#region src/helpers/atomic.ts
+var atomic_exports = /* @__PURE__ */ __exportAll({ writeFileAtomic: () => writeFileAtomic });
 /**
 * Write via a temp file in the same directory, then rename: readers never see a
 * half-written file, and a crash cannot truncate the previous config.
@@ -750,9 +773,14 @@ var init_atomic = __esmMin((() => {}));
 //#endregion
 //#region src/config/secrets.ts
 var secrets_exports = /* @__PURE__ */ __exportAll({
+	API_TOKEN_PREFIX: () => "hh_",
 	SecretsStore: () => SecretsStore,
+	apiTokenRecord: () => apiTokenRecord,
 	deriveKey: () => deriveKey,
+	generateApiToken: () => generateApiToken,
+	hashApiToken: () => hashApiToken,
 	hashPassword: () => hashPassword,
+	verifyApiToken: () => verifyApiToken,
 	verifyPassword: () => verifyPassword
 });
 function deriveKey(password, salt, cost, keylen) {
@@ -781,7 +809,27 @@ function verifyPassword(password, record) {
 	if (actual.length !== expected.length) return false;
 	return crypto.timingSafeEqual(actual, expected);
 }
-var COST, KEYLEN, SALT_BYTES, SecretsStore;
+function generateApiToken() {
+	return `hh_${crypto.randomBytes(API_TOKEN_BYTES).toString("base64url")}`;
+}
+function hashApiToken(token) {
+	return crypto.createHash("sha256").update(token, "utf8").digest("base64");
+}
+function verifyApiToken(token, record) {
+	if (token.length === 0) return false;
+	const expected = Buffer$1.from(record.hash, "base64");
+	const actual = Buffer$1.from(hashApiToken(token), "base64");
+	return crypto.timingSafeEqual(actual, expected);
+}
+function apiTokenRecord(token, now = Date.now()) {
+	return {
+		algo: "sha256",
+		hash: hashApiToken(token),
+		hint: token.slice(0, API_TOKEN_HINT_CHARS),
+		updatedAt: now
+	};
+}
+var COST, KEYLEN, SALT_BYTES, API_TOKEN_BYTES, API_TOKEN_HINT_CHARS, SecretsStore;
 var init_secrets = __esmMin((() => {
 	init_atomic();
 	COST = {
@@ -791,6 +839,8 @@ var init_secrets = __esmMin((() => {
 	};
 	KEYLEN = 64;
 	SALT_BYTES = 16;
+	API_TOKEN_BYTES = 32;
+	API_TOKEN_HINT_CHARS = 8;
 	SecretsStore = class {
 		file;
 		cache = null;
@@ -833,6 +883,16 @@ var init_secrets = __esmMin((() => {
 		get usingDefaultPassword() {
 			return this.password?.isDefault === true;
 		}
+		get apiToken() {
+			return this.load().apiToken;
+		}
+		get apiTokenSet() {
+			return this.apiToken !== null;
+		}
+		/** The readable head of the stored token, or null when none is set. */
+		get apiTokenHint() {
+			return this.apiToken?.hint ?? null;
+		}
 		get telegramToken() {
 			return this.load().telegram?.botToken ?? null;
 		}
@@ -858,6 +918,20 @@ var init_secrets = __esmMin((() => {
 				password: null
 			});
 		}
+		setApiToken(token) {
+			const record = apiTokenRecord(token);
+			this.save({
+				...this.load(),
+				apiToken: record
+			});
+			return record;
+		}
+		clearApiToken() {
+			this.save({
+				...this.load(),
+				apiToken: null
+			});
+		}
 		setTelegramToken(token) {
 			const trimmed = token?.trim() ?? "";
 			this.save({
@@ -867,21 +941,24 @@ var init_secrets = __esmMin((() => {
 		}
 		read() {
 			if (!fs.existsSync(this.file)) return {
-				version: 2,
+				version: 3,
 				password: null,
+				apiToken: null,
 				telegram: null
 			};
 			try {
 				const parsed = JSON.parse(fs.readFileSync(this.file, "utf8"));
 				return {
-					version: 2,
+					version: 3,
 					password: parsed?.password ?? null,
+					apiToken: parsed?.apiToken?.hash ? parsed.apiToken : null,
 					telegram: parsed?.telegram?.botToken ? { botToken: parsed.telegram.botToken } : null
 				};
 			} catch {
 				return {
-					version: 2,
+					version: 3,
 					password: null,
+					apiToken: null,
 					telegram: null
 				};
 			}
@@ -891,7 +968,21 @@ var init_secrets = __esmMin((() => {
 			this.cache = contents;
 		}
 	};
-})), SESSION_COOKIE, MAX_SESSIONS, MAX_LOCKOUT_MS, MAX_ATTEMPT_RECORDS, ATTEMPT_RECORD_TTL_MS, AuthService;
+}));
+//#endregion
+//#region src/services/auth.ts
+/**
+* `Authorization: Bearer <token>`; the scheme is case-insensitive per RFC 7235,
+* and the credential is taken whole so a stray space cannot silently shorten it.
+*/
+function bearerToken(header) {
+	if (!header) return null;
+	const [scheme, ...rest] = header.trim().split(/\s+/);
+	if (scheme?.toLowerCase() !== "bearer") return null;
+	const token = rest.join("");
+	return token.length > 0 ? token : null;
+}
+var SESSION_COOKIE, MAX_SESSIONS, MAX_LOCKOUT_MS, MAX_ATTEMPT_RECORDS, ATTEMPT_RECORD_TTL_MS, ANONYMOUS, AuthService;
 var init_auth$1 = __esmMin((() => {
 	init_secrets();
 	init_cookies();
@@ -900,6 +991,11 @@ var init_auth$1 = __esmMin((() => {
 	MAX_LOCKOUT_MS = 9e5;
 	MAX_ATTEMPT_RECORDS = 1e4;
 	ATTEMPT_RECORD_TTL_MS = 36e5;
+	ANONYMOUS = {
+		authenticated: false,
+		method: null,
+		session: null
+	};
 	AuthService = class {
 		secrets;
 		getConfig;
@@ -926,7 +1022,7 @@ var init_auth$1 = __esmMin((() => {
 		isEnabled() {
 			return this.getConfig().enabled;
 		}
-		/** On *and* usable: there is a password to check against. */
+		/** A password is set, so a browser has something to sign in with. */
 		isArmed() {
 			return this.getConfig().enabled && this.secrets.passwordSet;
 		}
@@ -934,11 +1030,44 @@ var init_auth$1 = __esmMin((() => {
 		isRequired() {
 			return this.isArmed();
 		}
-		sessionView(token) {
+		get apiTokenSet() {
+			return this.secrets.apiTokenSet;
+		}
+		/** The readable head of the stored token, never the token itself. */
+		get apiTokenHint() {
+			return this.secrets.apiTokenHint;
+		}
+		/** Compared against the stored SHA-256, in constant time. */
+		validateApiToken(token) {
+			if (token === null) return false;
+			const record = this.secrets.apiToken;
+			if (record === null) return false;
+			return verifyApiToken(token, record);
+		}
+		/**
+		* Resolves whichever credential the request carried. The token is only
+		* consulted when no session matched, so a stale cookie cannot mask it.
+		*/
+		authenticate(credentials) {
+			const session = this.validate(credentials.cookieToken);
+			if (session !== null) return {
+				authenticated: true,
+				method: "cookie",
+				session
+			};
+			if (this.validateApiToken(credentials.bearerToken)) return {
+				authenticated: true,
+				method: "token",
+				session: null
+			};
+			return ANONYMOUS;
+		}
+		sessionView(authenticated) {
 			return {
-				authenticated: this.validate(token) !== null,
+				authenticated,
 				authRequired: this.isRequired(),
 				passwordSet: this.secrets.passwordSet,
+				apiTokenSet: this.secrets.apiTokenSet,
 				usingDefaultPassword: this.secrets.usingDefaultPassword,
 				defaultPassword: this.secrets.usingDefaultPassword ? "hh" : null,
 				sessionTtlMs: this.getConfig().sessionTtlMs
@@ -1083,9 +1212,24 @@ var init_auth$1 = __esmMin((() => {
 //#endregion
 //#region src/middleware/auth.ts
 /**
+* The one place that reads a request's credentials, so the guard, the session
+* route and `/healthz` can never disagree about who is calling.
+*/
+function requestIdentity(c, auth) {
+	return auth.authenticate({
+		cookieToken: auth.tokenFromCookie(c.req.header("cookie")),
+		bearerToken: bearerToken(c.req.header("authorization"))
+	});
+}
+/**
 * Guards every `/api/*` route. The SPA shell stays public (it holds no data),
 * so the browser can load the app and show the login screen.
 *
+* A request may prove itself with the session cookie or with an API token
+* (`Authorization: Bearer …`), which is what lets a script or an agent drive the
+* panel without a browser. The token also works while auth is enabled but no
+* password is set — that state otherwise only trusts this machine.
+*
 * State-changing requests that carry an `Origin` must come from this same host:
 * with `SameSite=Strict` cookies that closes the cross-site CSRF path.
 */
@@ -1111,14 +1255,17 @@ function createAuthGuard(deps) {
 				}
 			}
 			if (!PUBLIC_PATHS.has(path)) {
+				const identity = requestIdentity(c, deps.auth);
 				if (deps.auth.isArmed()) {
-					const token = deps.auth.tokenFromCookie(c.req.header("cookie"));
-					if (deps.auth.validate(token) === null) throw new DetailedError("authentication required", {
-						statusCode: 401,
-						code: AUTH_REQUIRED_CODE
-					});
+					if (!identity.authenticated) {
+						if (deps.auth.apiTokenSet) c.header("WWW-Authenticate", "Bearer realm=\"home-hosted\"");
+						throw new DetailedError("authentication required", {
+							statusCode: 401,
+							code: AUTH_REQUIRED_CODE
+						});
+					}
 				} else if (deps.auth.isEnabled()) {
-					if (!isLoopbackRequest(c)) throw new DetailedError("authentication is enabled but no password is set — set one from the machine running the panel", {
+					if (!identity.authenticated && !isLoopbackRequest(c)) throw new DetailedError("authentication is enabled but no password is set — set one from the machine running the panel", {
 						statusCode: 401,
 						code: "AUTH_UNARMED"
 					});
@@ -1211,7 +1358,7 @@ function createAuthRoute(deps) {
 			description: "Session",
 			content: jsonBody(sessionViewSchema)
 		} }
-	}), (c) => c.json(deps.auth.sessionView(deps.auth.tokenFromCookie(c.req.header("cookie"))))).post("/auth/login", describeRoute({
+	}), (c) => c.json(deps.auth.sessionView(requestIdentity(c, deps.auth).authenticated))).post("/auth/login", describeRoute({
 		tags: ["auth"],
 		summary: "Exchange the panel password for a session cookie",
 		responses: {
@@ -1238,7 +1385,7 @@ function createAuthRoute(deps) {
 			sameSite: "Strict",
 			httpOnly: true
 		}));
-		return c.json(deps.auth.sessionView(outcome.token));
+		return c.json(deps.auth.sessionView(true));
 	}).post("/auth/logout", describeRoute({
 		tags: ["auth"],
 		summary: "Drop the session cookie",
@@ -1262,14 +1409,14 @@ function createAuthRoute(deps) {
 		}
 	}), validate("json", passwordSchema), (c) => {
 		const body = c.req.valid("json");
+		const identity = requestIdentity(c, deps.auth);
 		const hadPassword = deps.auth.passwordSet;
-		const authenticated = deps.auth.validate(deps.auth.tokenFromCookie(c.req.header("cookie"))) !== null;
 		const firstSetup = !hadPassword && isLoopbackRequest(c);
-		if (!authenticated && !firstSetup) throw new DetailedError("authentication required", {
+		if (!identity.authenticated && !firstSetup) throw new DetailedError("authentication required", {
 			statusCode: 401,
 			code: AUTH_REQUIRED_CODE
 		});
-		if (authenticated && hadPassword) {
+		if (identity.authenticated && hadPassword) {
 			if (body.currentPassword === void 0) throw new DetailedError("currentPassword is required to change an existing password", {
 				statusCode: 400,
 				code: "CURRENT_PASSWORD_REQUIRED"
@@ -1279,7 +1426,7 @@ function createAuthRoute(deps) {
 				code: "CURRENT_PASSWORD_WRONG"
 			});
 		}
-		deps.auth.setPassword(body.newPassword, { keepToken: deps.auth.tokenFromCookie(c.req.header("cookie")) });
+		deps.auth.setPassword(body.newPassword, { keepToken: identity.session?.token ?? null });
 		let enabled = deps.store.config.control.auth.enabled;
 		if (!enabled) {
 			deps.store.updateControl({ auth: { enabled: true } });
@@ -1299,7 +1446,7 @@ function createAuthRoute(deps) {
 			401: ERROR_RESPONSES[401]
 		}
 	}), (c) => {
-		if (deps.auth.validate(deps.auth.tokenFromCookie(c.req.header("cookie"))) === null) throw new DetailedError("authentication required", {
+		if (!requestIdentity(c, deps.auth).authenticated) throw new DetailedError("authentication required", {
 			statusCode: 401,
 			code: AUTH_REQUIRED_CODE
 		});
@@ -1432,6 +1579,7 @@ function buildControlView(store, auth, control, tls) {
 			enabled: config.auth.enabled,
 			passwordSet: auth.passwordSet,
 			passwordUpdatedAt: auth.passwordUpdatedAt,
+			apiTokenSet: auth.apiTokenSet,
 			usingDefaultPassword: auth.usingDefaultPassword,
 			exposed: exposure.exposed,
 			blockedReason: exposure.blockedReason,
@@ -1800,7 +1948,7 @@ function createHealthRoute(deps) {
 	}), (c) => {
 		const state = deps.supervisor.getState();
 		const broken = state.servers.filter((server) => server.config.autostart && server.status === "crashed");
-		const authenticated = deps.auth.validate(deps.auth.tokenFromCookie(c.req.header("cookie"))) !== null;
+		const authenticated = requestIdentity(c, deps.auth).authenticated;
 		return c.json({
 			status: broken.length > 0 ? "degraded" : "ok",
 			uptimeMs: Math.round(process.uptime() * 1e3),
@@ -1819,6 +1967,7 @@ function createHealthRoute(deps) {
 var init_health = __esmMin((() => {
 	init_factory();
 	init_openapi$1();
+	init_auth();
 }));
 //#endregion
 //#region src/api/logs.ts
@@ -2137,12 +2286,49 @@ var init_notifications$1 = __esmMin((() => {
 	init_contracts();
 }));
 //#endregion
+//#region src/config/migrations.ts
+var migrations_exports = /* @__PURE__ */ __exportAll({
+	CONFIG_SCHEMA: () => 1,
+	applyConfigMigrations: () => applyConfigMigrations,
+	configMigrations: () => configMigrations,
+	planConfigMigrations: () => planConfigMigrations
+});
+/** What would have to run to bring `from` up to `to`. */
+function planConfigMigrations(from, options = {}) {
+	const to = options.to ?? 1;
+	return {
+		from,
+		to,
+		steps: (options.migrations ?? configMigrations).filter((migration) => migration.to > from && migration.to <= to).sort((a, b) => a.to - b.to),
+		tooNew: from > to
+	};
+}
+/** Applies the plan in order; the caller owns writing the result. */
+function applyConfigMigrations(config, from, options = {}) {
+	const { steps } = planConfigMigrations(from, options);
+	let current = config;
+	for (const step of steps) current = step.apply(current);
+	return {
+		config: current,
+		applied: steps
+	};
+}
+var configMigrations;
+var init_migrations = __esmMin((() => {
+	configMigrations = [];
+}));
+//#endregion
 //#region src/config/schema.ts
-var configSchema;
+var metaSchema, configSchema, CONFIG_KEYS;
 var init_schema = __esmMin((() => {
 	init_contracts();
+	metaSchema = type({
+		writtenBy: "string = \"\"",
+		schema: "number.integer >= 1 = 1"
+	}).onUndeclaredKey("reject");
 	configSchema = type({
 		$schema: "string?",
+		meta: metaSchema.optional(),
 		control: controlSchema.default(() => ({})),
 		defaults: defaultsSchema.default(() => ({})),
 		logs: logsSchema.default(() => ({})),
@@ -2151,6 +2337,240 @@ var init_schema = __esmMin((() => {
 		backups: backupsSchema.default(() => ({})),
 		servers: serverSchema.array().default(() => [])
 	}).onUndeclaredKey("reject");
+	CONFIG_KEYS = [
+		"$schema",
+		"meta",
+		"control",
+		"defaults",
+		"logs",
+		"notifications",
+		"host",
+		"backups",
+		"servers"
+	];
+}));
+//#endregion
+//#region src/helpers/version.ts
+var version_exports = /* @__PURE__ */ __exportAll({ appVersion: () => appVersion });
+/**
+* The running release, read from the package manifest.
+*
+* The caller may be `src/**` under tsx or the built `dist/cli.js`, so the manifest
+* is found by walking up rather than by a fixed relative path. `src/cli.ts` keeps
+* its own read because it may only import node builtins statically.
+*/
+function appVersion() {
+	if (cached !== null) return cached;
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	for (let depth = 0; depth < 4; depth++) {
+		try {
+			const manifest = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+			if (manifest.name === "home-hosted" && typeof manifest.version === "string") {
+				cached = manifest.version;
+				return cached;
+			}
+		} catch {}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	cached = "0.0.0";
+	return cached;
+}
+var cached;
+var init_version = __esmMin((() => {
+	cached = null;
+}));
+//#endregion
+//#region src/config/parse.ts
+var parse_exports = /* @__PURE__ */ __exportAll({
+	parseConfig: () => parseConfig,
+	stampConfig: () => stampConfig
+});
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deleteAtPath(root, path) {
+	let node = root;
+	for (const key of path.slice(0, -1)) {
+		node = Array.isArray(node) ? node[Number(key)] : isRecord$1(node) ? node[key] : void 0;
+		if (node === void 0) return;
+	}
+	const last = path[path.length - 1];
+	if (last === void 0) return;
+	if (isRecord$1(node)) delete node[String(last)];
+	else if (Array.isArray(node) && typeof last === "number") node.splice(last, 1);
+}
+/**
+* Validates one object against one schema, tolerating keys the schema does not
+* know: a config written by a newer release has to keep working here, and losing
+* the *whole group* to schema defaults would silently reset the listener port,
+* the bind and the auth policy over a single unrecognized key.
+*
+* Only unrecognized keys are dropped, and each one is reported. Anything else is
+* a real problem, returned for the caller to refuse on.
+*/
+function parseTolerant(value, schema, prefix, unknownKeys) {
+	const candidate = structuredClone(value);
+	for (let pass = 0; pass < 25; pass++) {
+		const parsed = schema(candidate);
+		if (!(parsed instanceof type.errors)) return {
+			value: parsed,
+			error: null
+		};
+		const removable = parsed.filter((problem) => problem.problem === UNDECLARED);
+		if (removable.length === 0) return {
+			value: null,
+			error: parsed.summary
+		};
+		if (!isRecord$1(candidate)) return {
+			value: null,
+			error: parsed.summary
+		};
+		for (const problem of removable) {
+			const at = `${prefix}.${problem.path.join(".")}`;
+			if (!unknownKeys.includes(at)) unknownKeys.push(at);
+			deleteAtPath(candidate, problem.path);
+		}
+	}
+	return {
+		value: null,
+		error: "too many unrecognized keys to ignore"
+	};
+}
+/**
+* Reads a `servers.config.json` from any release. Unrecognized keys are reported
+* and left on disk; blocking problems — including a file this release cannot
+* understand — land in `errors` and leave `config` null.
+*/
+function parseConfig(raw, options = {}) {
+	const unknownKeys = [];
+	const errors = [];
+	const warnings = [];
+	const result = {
+		config: null,
+		errors,
+		unknownKeys,
+		warnings,
+		schemaVersion: 1,
+		writtenBy: null
+	};
+	if (!isRecord$1(raw)) {
+		errors.push("the config must contain a JSON object");
+		return result;
+	}
+	const meta = isRecord$1(raw.meta) ? raw.meta : null;
+	const schemaVersion = typeof meta?.schema === "number" ? meta.schema : 1;
+	const writtenBy = typeof meta?.writtenBy === "string" && meta.writtenBy.length > 0 ? meta.writtenBy : null;
+	result.schemaVersion = schemaVersion;
+	result.writtenBy = writtenBy;
+	if (schemaVersion > 1) {
+		errors.push(`written by home-hosted ${writtenBy ?? "a newer release"} (config schema ${schemaVersion}); this release understands schema 1`);
+		return result;
+	}
+	const { steps } = planConfigMigrations(schemaVersion, options);
+	if (steps.length > 0) {
+		errors.push(`config schema ${schemaVersion} needs ${steps.length} migration${steps.length === 1 ? "" : "s"} before this release can use it`);
+		return result;
+	}
+	for (const key of Object.keys(raw)) if (!CONFIG_KEYS.includes(key)) unknownKeys.push(key);
+	const groups = {};
+	for (const [name, schema] of GROUPS) {
+		const parsed = parseTolerant(raw[name] ?? {}, schema, name, unknownKeys);
+		if (parsed.error !== null) errors.push(`${name}: ${parsed.error}`);
+		groups[name] = parsed.value ?? schema({});
+	}
+	const defaults = groups.defaults;
+	const servers = [];
+	const seen = /* @__PURE__ */ new Set();
+	(Array.isArray(raw.servers) ? raw.servers : []).forEach((entry, index) => {
+		const label = `servers[${index}]`;
+		const parsed = parseTolerant(isRecord$1(entry) ? {
+			...defaults,
+			...entry
+		} : entry, serverSchema, label, unknownKeys);
+		if (parsed.error !== null) {
+			const id = isRecord$1(entry) ? entry.id : void 0;
+			errors.push(`${label}${typeof id === "string" ? ` ("${id}")` : ""}: ${parsed.error}`);
+			return;
+		}
+		const server = parsed.value;
+		if (seen.has(server.id)) {
+			errors.push(`${label}: duplicate id "${server.id}"`);
+			return;
+		}
+		seen.add(server.id);
+		servers.push({
+			...server,
+			port: server.port ?? null
+		});
+	});
+	warnings.push(...validateDependencies(servers));
+	if (errors.length > 0) return result;
+	result.config = {
+		meta: {
+			writtenBy: writtenBy ?? "",
+			schema: schemaVersion
+		},
+		control: groups.control,
+		defaults,
+		logs: groups.logs,
+		notifications: groups.notifications,
+		host: groups.host,
+		backups: groups.backups,
+		servers
+	};
+	return result;
+}
+/** Dangling dependencies and cycles are reported, not fatal: supervision still runs. */
+function validateDependencies(servers) {
+	const ids = new Set(servers.map((server) => server.id));
+	const errors = [];
+	for (const server of servers) for (const dependency of server.dependsOn) if (dependency === server.id) errors.push(`"${server.id}" depends on itself`);
+	else if (!ids.has(dependency)) errors.push(`"${server.id}" depends on unknown server "${dependency}"`);
+	const visiting = /* @__PURE__ */ new Set();
+	const settled = /* @__PURE__ */ new Set();
+	const byId = new Map(servers.map((server) => [server.id, server]));
+	const walk = (id) => {
+		if (settled.has(id)) return;
+		if (visiting.has(id)) {
+			errors.push(`dependency cycle through "${id}"`);
+			return;
+		}
+		visiting.add(id);
+		for (const dependency of byId.get(id)?.dependsOn ?? []) walk(dependency);
+		visiting.delete(id);
+		settled.add(id);
+	};
+	for (const server of servers) walk(server.id);
+	return [...new Set(errors)];
+}
+/** Adds the stamp every write carries, so the next release can tell what wrote the file. */
+function stampConfig(draft) {
+	const { $schema, meta: _meta, ...rest } = draft;
+	return {
+		...$schema === void 0 ? {} : { $schema },
+		meta: {
+			writtenBy: appVersion(),
+			schema: 1
+		},
+		...rest
+	};
+}
+var GROUPS, UNDECLARED;
+var init_parse = __esmMin((() => {
+	init_migrations();
+	init_schema();
+	init_version();
+	GROUPS = [
+		["control", controlSchema],
+		["defaults", defaultsSchema],
+		["logs", logsSchema],
+		["notifications", notificationsSchema],
+		["host", hostSchema],
+		["backups", backupsSchema]
+	];
+	UNDECLARED = "must be removed";
 }));
 //#endregion
 //#region src/config/seed.ts
@@ -2180,30 +2600,6 @@ function formatErrors(errors) {
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** Dangling dependencies and cycles are reported, not fatal: supervision still runs. */
-function validateDependencies(servers) {
-	const ids = new Set(servers.map((server) => server.id));
-	const errors = [];
-	for (const server of servers) for (const dependency of server.dependsOn) if (dependency === server.id) errors.push(`"${server.id}" depends on itself`);
-	else if (!ids.has(dependency)) errors.push(`"${server.id}" depends on unknown server "${dependency}"`);
-	const visiting = /* @__PURE__ */ new Set();
-	const done = /* @__PURE__ */ new Set();
-	const byId = new Map(servers.map((server) => [server.id, server]));
-	const walk = (id, trail) => {
-		if (done.has(id)) return;
-		if (visiting.has(id)) {
-			errors.push(`dependency cycle: ${[...trail, id].join(" -> ")}`);
-			return;
-		}
-		visiting.add(id);
-		for (const dependency of byId.get(id)?.dependsOn ?? []) if (ids.has(dependency) && dependency !== id) walk(dependency, [...trail, id]);
-		visiting.delete(id);
-		done.add(id);
-	};
-	for (const server of servers) walk(server.id, []);
-	return errors;
-}
-/** Nested groups merge so a partial edit never drops a sibling field. */
 function applyPatch(target, patch, mergeKeys) {
 	for (const [key, value] of Object.entries(patch)) {
 		if (value === void 0) continue;
@@ -2238,6 +2634,8 @@ function mergeGroup(target, patch) {
 }
 var SERVER_MERGE_KEYS, CONTROL_MERGE_KEYS, NOTIFICATION_MERGE_KEYS, EMPTY_MERGE_KEYS, ConfigError, ConfigStore;
 var init_store = __esmMin((() => {
+	init_migrations();
+	init_parse();
 	init_schema();
 	init_seed();
 	init_atomic();
@@ -2259,6 +2657,8 @@ var init_store = __esmMin((() => {
 		raw = {};
 		resolvedConfig;
 		error = null;
+		warnings = [];
+		schemaVersion = 1;
 		listeners = /* @__PURE__ */ new Set();
 		constructor(file, seed = SEED_CONFIG) {
 			this.file = file;
@@ -2273,6 +2673,18 @@ var init_store = __esmMin((() => {
 		get configError() {
 			return this.error;
 		}
+		/** Keys a newer release wrote that this one ignores; nothing to refuse over. */
+		get configWarnings() {
+			return [...this.warnings];
+		}
+		/** The shape the file declares, as last read. */
+		get configSchemaVersion() {
+			return this.schemaVersion;
+		}
+		/** Steps that would have to run before this release could use the file. */
+		get pendingMigrations() {
+			return planConfigMigrations(this.schemaVersion).steps;
+		}
 		get servers() {
 			return this.resolvedConfig.servers;
 		}
@@ -2299,7 +2711,7 @@ var init_store = __esmMin((() => {
 		}
 		read() {
 			if (!fs.existsSync(this.file)) {
-				const seed = structuredClone(this.seed);
+				const seed = stampConfig(structuredClone(this.seed));
 				writeFileAtomic(this.file, `${JSON.stringify(seed, null, 2)}\n`);
 				this.raw = seed;
 				this.apply(seed);
@@ -2314,12 +2726,6 @@ var init_store = __esmMin((() => {
 				this.resolvedConfig = this.resolveFallback();
 				return;
 			}
-			if (!isRecord(parsed)) {
-				this.error = `${path.basename(this.file)} must contain a JSON object`;
-				this.raw = {};
-				this.resolvedConfig = this.resolveFallback();
-				return;
-			}
 			this.apply(parsed);
 		}
 		notify() {
@@ -2423,9 +2829,10 @@ var init_store = __esmMin((() => {
 			};
 		}
 		commit(draft) {
-			writeFileAtomic(this.file, `${JSON.stringify(draft, null, 2)}\n`);
-			this.raw = draft;
-			this.apply(draft);
+			const stamped = stampConfig(draft);
+			writeFileAtomic(this.file, `${JSON.stringify(stamped, null, 2)}\n`);
+			this.raw = stamped;
+			this.apply(stamped);
 			this.notify();
 		}
 		resolveFallback() {
@@ -2449,53 +2856,12 @@ var init_store = __esmMin((() => {
 		}
 		apply(raw) {
 			this.raw = raw;
-			const errors = [];
-			const control = controlSchema(raw.control ?? {});
-			const defaults = defaultsSchema(raw.defaults ?? {});
-			const logs = logsSchema(raw.logs ?? {});
-			const notifications = notificationsSchema(raw.notifications ?? {});
-			const host = hostSchema(raw.host ?? {});
-			const backups = backupsSchema(raw.backups ?? {});
-			if (control instanceof type.errors) errors.push(`control: ${formatErrors(control)}`);
-			if (defaults instanceof type.errors) errors.push(`defaults: ${formatErrors(defaults)}`);
-			if (logs instanceof type.errors) errors.push(`logs: ${formatErrors(logs)}`);
-			if (notifications instanceof type.errors) errors.push(`notifications: ${formatErrors(notifications)}`);
-			if (host instanceof type.errors) errors.push(`host: ${formatErrors(host)}`);
-			if (backups instanceof type.errors) errors.push(`backups: ${formatErrors(backups)}`);
-			const resolvedDefaults = defaults instanceof type.errors ? defaultsSchema({}) : defaults;
-			const servers = [];
-			const seen = /* @__PURE__ */ new Set();
-			(Array.isArray(raw.servers) ? raw.servers : []).forEach((entry, index) => {
-				const parsed = serverSchema({
-					...resolvedDefaults,
-					...entry
-				});
-				if (parsed instanceof type.errors) {
-					errors.push(`servers[${index}] (${entry?.id ?? "no id"}): ${formatErrors(parsed)}`);
-					return;
-				}
-				if (seen.has(parsed.id)) {
-					errors.push(`servers[${index}]: duplicate id "${parsed.id}"`);
-					return;
-				}
-				seen.add(parsed.id);
-				servers.push({
-					...parsed,
-					port: parsed.port ?? null
-				});
-			});
-			errors.push(...validateDependencies(servers));
-			this.error = errors.length > 0 ? errors.join("; ") : null;
-			this.resolvedConfig = {
-				$schema: raw.$schema,
-				control: control instanceof type.errors ? controlSchema({}) : control,
-				defaults: resolvedDefaults,
-				logs: logs instanceof type.errors ? logsSchema({}) : logs,
-				notifications: notifications instanceof type.errors ? notificationsSchema({}) : notifications,
-				host: host instanceof type.errors ? hostSchema({}) : host,
-				backups: backups instanceof type.errors ? backupsSchema({}) : backups,
-				servers
-			};
+			const parsed = parseConfig(raw);
+			this.error = parsed.errors.length > 0 ? parsed.errors.join("; ") : null;
+			this.schemaVersion = parsed.schemaVersion;
+			this.warnings = [...parsed.warnings, ...parsed.unknownKeys.length === 0 ? [] : [`${path.basename(this.file)} carries ${parsed.unknownKeys.length} unrecognized key(s) this release ignores: ${parsed.unknownKeys.join(", ")}`]];
+			if (parsed.config !== null) this.resolvedConfig = parsed.config;
+			else if (this.resolvedConfig === void 0) this.resolvedConfig = this.resolveFallback();
 		}
 	};
 }));
@@ -2681,6 +3047,25 @@ function createServersRoute(deps) {
 	}), validate("param", idParam), (c) => {
 		deps.supervisor.clearLogs(c.req.valid("param").id);
 		return c.json({ ok: true });
+	}).post("/:id/free-port", describeRoute({
+		tags: ["servers"],
+		summary: "Ask whatever holds this server's port to stop",
+		responses: {
+			200: {
+				description: "What was signalled",
+				content: jsonBody(freePortResultSchema)
+			},
+			404: ERROR_RESPONSES[404],
+			409: { description: "Nothing to free, or the holder is supervised by this panel" }
+		}
+	}), validate("param", idParam), async (c) => {
+		const { id } = c.req.valid("param");
+		const result = await deps.supervisor.freePort(id);
+		if (!result.ok) throw new DetailedError(result.error ?? `could not free the port for "${id}"`, {
+			statusCode: statusFor(result),
+			code: "FREE_PORT_FAILED"
+		});
+		return c.json(result);
 	}).patch("/:id", describeRoute({
 		tags: ["servers"],
 		summary: "Edit a server",
@@ -3197,7 +3582,7 @@ var init_app = __esmMin((() => {
 //#region src/helpers/daemon.ts
 var daemon_exports = /* @__PURE__ */ __exportAll({
 	clearRuntime: () => clearRuntime,
-	isProcessAlive: () => isProcessAlive,
+	isProcessAlive: () => isProcessAlive$1,
 	newToken: () => newToken,
 	probeRuntime: () => probeRuntime,
 	readRuntime: () => readRuntime,
@@ -3223,7 +3608,7 @@ function newToken() {
 	return randomBytes(32).toString("base64url");
 }
 /** Signal 0 only probes the pid; `EPERM` still means the process is there. */
-function isProcessAlive(pid) {
+function isProcessAlive$1(pid) {
 	try {
 		process.kill(pid, 0);
 		return true;
@@ -3361,6 +3746,46 @@ async function killPortHolders(port) {
 	} catch {}
 	return pids;
 }
+/** Signal 0 asks the OS whether the pid still exists, without touching it. */
+function isProcessAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function signalPid$1(pid, name) {
+	try {
+		process.kill(pid, name);
+	} catch {}
+}
+function delay$3(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Asks specific pids to leave, politely first: a stray dev server stops on
+* SIGTERM, and only what ignores it is killed. Deciding *which* pids may be
+* touched belongs to the caller — this only does the signalling.
+*/
+async function terminatePids(pids, options = {}) {
+	const graceMs = options.graceMs ?? 3e3;
+	const aliveBefore = [...new Set(pids)].filter(isProcessAlive);
+	for (const pid of aliveBefore) signalPid$1(pid, "SIGTERM");
+	const deadline = Date.now() + graceMs;
+	let alive = aliveBefore.filter(isProcessAlive);
+	while (alive.length > 0 && Date.now() < deadline) {
+		await delay$3(100);
+		alive = alive.filter(isProcessAlive);
+	}
+	const stopped = aliveBefore.filter((pid) => !alive.includes(pid));
+	for (const pid of alive) signalPid$1(pid, "SIGKILL");
+	if (alive.length > 0 && graceMs > 0) await delay$3(150);
+	return {
+		stopped,
+		forced: alive
+	};
+}
 /** `netstat -ano` lines: `  TCP    127.0.0.1:4010    0.0.0.0:0    LISTENING    1234` */
 function parseNetstatListeners(output, port) {
 	const pids = /* @__PURE__ */ new Set();
@@ -3880,6 +4305,39 @@ function collectTree(rootPid, children) {
 	}
 	return pids;
 }
+/**
+* Does this process carry the environment the supervisor gave the entry?
+*
+* A program that restarts itself — especially a plugin doing it — leaves behind a
+* detached process that still inherits `HHOSTED_SERVER_ID`, and that marker is what
+* tells a legitimate successor apart from a stranger squatting on the port.
+*
+* Linux reads `/proc`; macOS asks `ps -E`; Windows has no per-process environment,
+* so the answer is always "no" there and ownership falls back to the port policy.
+*/
+async function processCarriesServerId(pid, serverId) {
+	if (serverId.length === 0) return false;
+	const needle = `HHOSTED_SERVER_ID=${serverId}`;
+	if (process.platform === "linux") try {
+		return (await fs.promises.readFile(`/proc/${pid}/environ`, "utf8")).split("\0").includes(needle);
+	} catch {
+		return false;
+	}
+	if (process.platform === "darwin") try {
+		const { stdout } = await execFileAsync$2("ps", [
+			"-p",
+			String(pid),
+			"-E",
+			"-ww",
+			"-o",
+			"command="
+		], { timeout: 3e3 });
+		return new RegExp(`(?:^|\\s)${needle}(?:\\s|$)`).test(stdout);
+	} catch {
+		return false;
+	}
+	return false;
+}
 var execFileAsync$2, clockTicks, ProcessSampler;
 var init_proc = __esmMin((() => {
 	execFileAsync$2 = promisify(execFile);
@@ -4016,6 +4474,9 @@ async function killTreeWindows(pid) {
 function signalChild(child, signal, killGroup) {
 	const pid = child.pid;
 	if (pid === void 0) return;
+	signalPid(pid, signal, killGroup);
+}
+function signalPid(pid, signal, killGroup) {
 	if (process.platform === "win32") {
 		if (killGroup) killTreeWindows(pid);
 		else try {
@@ -4031,6 +4492,33 @@ function signalChild(child, signal, killGroup) {
 		process.kill(pid, signal);
 	} catch {}
 }
+function alive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* The same shutdown a supervised child gets, for a process we adopted instead of
+* spawned: a detached successor is not our child, so it is signalled by pid (and
+* by process group when asked) and its exit is polled rather than awaited.
+*/
+async function terminatePid(pid, options) {
+	if (!alive(pid)) return "exited";
+	signalPid(pid, options.signal, options.killGroup);
+	const deadline = Date.now() + Math.max(0, options.graceMs);
+	while (Date.now() < deadline && alive(pid)) await delay$2(50);
+	if (!alive(pid)) return "exited";
+	signalPid(pid, "SIGKILL", options.killGroup);
+	const hardDeadline = Date.now() + 2e3;
+	while (Date.now() < hardDeadline && alive(pid)) await delay$2(50);
+	return "force-killed";
+}
+function delay$2(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function waitForExit$1(child, timeoutMs) {
 	if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true);
 	if (timeoutMs <= 0) return Promise.resolve(false);
@@ -4259,10 +4747,11 @@ var init_supervisor = __esmMin((() => {
 					error: "supervisor is shutting down"
 				};
 				const conflict = await this.preflight(entry);
-				if (conflict !== null) return {
+				if (conflict.kind === "blocked") return {
 					ok: false,
-					error: conflict
+					error: conflict.error
 				};
+				if (conflict.kind === "adopt") return this.adoptEntry(entry, conflict.pid);
 				return this.spawnEntry(entry);
 			} finally {
 				entry.starting = false;
@@ -4280,6 +4769,97 @@ var init_supervisor = __esmMin((() => {
 			await this.stop(id);
 			return this.start(id);
 		}
+		/**
+		* Frees the port this entry wants, by asking whatever listens on it to leave.
+		*
+		* The pid is never taken from a message: holders are listed again here, and a
+		* listener this panel supervises is refused rather than killed — a port held by
+		* a sibling entry is a configuration mistake, not a stray process. That also
+		* keeps a stale `(pid 1234)` in an old banner from killing a recycled pid.
+		*/
+		async freePort(id) {
+			const entry = this.entries.get(id);
+			const empty = {
+				ok: false,
+				port: null,
+				terminated: [],
+				forced: [],
+				skipped: [],
+				free: false
+			};
+			if (!entry) return {
+				...empty,
+				error: `unknown server "${id}"`
+			};
+			const port = entry.config.port;
+			if (port === null) return {
+				...empty,
+				error: `server "${id}" has no port configured`
+			};
+			if (entry.starting || entry.stopping) return {
+				...empty,
+				port,
+				error: `server "${id}" is busy — try again in a moment`
+			};
+			const supervised = this.supervisedPids();
+			const holders = await listPortHolders(port);
+			const ours = holders.filter((pid) => supervised.has(pid));
+			const foreign = holders.filter((pid) => !supervised.has(pid));
+			if (holders.length === 0) return {
+				...empty,
+				port,
+				error: `nothing is listening on port ${port} any more`
+			};
+			if (foreign.length === 0) {
+				const reason = `port ${port} is held by pid ${ours.join(", ")}, which this panel supervises — stop that server instead`;
+				return {
+					...empty,
+					port,
+					error: reason,
+					skipped: ours
+				};
+			}
+			this.log(entry, "system", `freeing port ${port}: asking pid ${foreign.join(", ")} to stop`);
+			const { stopped, forced } = await terminatePids(foreign);
+			if (forced.length > 0) this.log(entry, "system", `pid ${forced.join(", ")} ignored SIGTERM and was killed`);
+			const free = await this.waitForPortRelease(entry, port);
+			if (free) {
+				if (entry.status === "conflict") {
+					entry.status = "stopped";
+					entry.lastError = null;
+				}
+				entry.portState = "free";
+				this.log(entry, "system", `port ${port} is free${ours.length > 0 ? ` (pid ${ours.join(", ")} left untouched)` : ""}`);
+				this.publishServer(entry);
+			} else {
+				entry.lastError = `port ${port} is still in use after killing pid ${foreign.join(", ")}`;
+				this.log(entry, "system", entry.lastError);
+				this.publishServer(entry);
+			}
+			return {
+				ok: true,
+				port,
+				terminated: stopped,
+				forced,
+				skipped: ours,
+				free
+			};
+		}
+		/** Pids of the child processes this panel owns, plus itself. */
+		supervisedPids() {
+			const pids = /* @__PURE__ */ new Set([process.pid]);
+			for (const entry of this.entries.values()) if (entry.pid !== null) pids.add(entry.pid);
+			return pids;
+		}
+		/** The port's own answer, with the same short recheck the preflight uses. */
+		async waitForPortRelease(entry, port) {
+			const freeOnAll = async () => {
+				return (await Promise.all(this.occupancyHosts(entry).map((host) => isPortFree(port, host)))).every(Boolean);
+			};
+			if (await freeOnAll()) return true;
+			await delay$1(PORT_RELEASE_RECHECK_MS);
+			return freeOnAll();
+		}
 		clearLogs(id) {
 			const entry = this.entries.get(id);
 			if (!entry) return;
@@ -4351,15 +4931,14 @@ var init_supervisor = __esmMin((() => {
 			this.clearRetry(entry);
 			entry.nextRetryAt = null;
 			entry.stopping = true;
-			if (entry.child === null) {
+			if (entry.child === null && entry.pid === null) {
 				entry.status = "stopped";
-				entry.pid = null;
 				this.publishServer(entry);
 				return { ok: true };
 			}
 			entry.status = "stopping";
 			this.publishServer(entry);
-			if (await terminate(entry.child, entry.config.stop) === "force-killed") this.log(entry, "system", "force-killed after grace period");
+			if ((entry.child === null && entry.pid !== null ? await terminatePid(entry.pid, entry.config.stop) : await terminate(entry.child, entry.config.stop)) === "force-killed") this.log(entry, "system", "force-killed after grace period");
 			const { port, stop } = entry.config;
 			if (stop.killPortHolders && port !== null) {
 				const leftover = await listPortHolders(port);
@@ -4371,6 +4950,7 @@ var init_supervisor = __esmMin((() => {
 			entry.stopping = false;
 			entry.child = null;
 			entry.pid = null;
+			entry.adopted = false;
 			entry.status = "stopped";
 			this.log(entry, "system", "stopped");
 			this.publishServer(entry);
@@ -4396,6 +4976,7 @@ var init_supervisor = __esmMin((() => {
 				lastProbeAt: 0,
 				lastOccupancyProbeAt: 0,
 				probing: false,
+				adopted: false,
 				starting: false,
 				stopping: false,
 				bootstrapDone: !config.bootstrap,
@@ -4450,9 +5031,20 @@ var init_supervisor = __esmMin((() => {
 		async portAccepts(entry, port, timeoutMs) {
 			return (await Promise.all(this.occupancyHosts(entry).map((host) => probePort(host, port, timeoutMs)))).some(Boolean);
 		}
+		/**
+		* The port holders that carry this entry's own marker — a program that restarted
+		* itself leaves a detached process behind, and that process is the *same server*,
+		* not a stranger to kill. Read from the environment the supervisor gave the entry,
+		* which a successor inherits unless it scrubs it.
+		*/
+		async ownPortHolders(entry, holders) {
+			const own = [];
+			for (const pid of holders) if (await processCarriesServerId(pid, entry.config.id)) own.push(pid);
+			return own;
+		}
 		async preflight(entry) {
 			const port = entry.config.port;
-			if (port === null) return null;
+			if (port === null) return { kind: "free" };
 			const hosts = this.occupancyHosts(entry);
 			const freeOnAll = async () => {
 				return (await Promise.all(hosts.map((host) => isPortFree(port, host)))).every(Boolean);
@@ -4463,18 +5055,80 @@ var init_supervisor = __esmMin((() => {
 				free = await freeOnAll();
 			}
 			entry.portState = free ? "free" : "in-use";
-			if (free) return null;
+			if (free) return { kind: "free" };
 			const holders = await listPortHolders(port);
+			const own = await this.ownPortHolders(entry, holders);
 			const suffix = holders.length > 0 ? ` (pid ${holders.join(", ")})` : "";
-			if (entry.config.onPortConflict === "block") {
+			if (own.length > 0 && entry.config.onPortConflict === "follow") return {
+				kind: "adopt",
+				pid: own[0]
+			};
+			if (own.length > 0 && entry.config.onPortConflict === "reclaim") {
+				this.log(entry, "system", `port ${port} is held by pid ${own.join(", ")}, a detached restart of this entry — replacing it with a supervised process`);
+				const { forced } = await terminatePids(own);
+				if (forced.length > 0) this.log(entry, "system", `pid ${forced.join(", ")} ignored SIGTERM and was killed`);
+				await delay$1(PORT_RELEASE_RECHECK_MS);
+				if (await freeOnAll()) {
+					entry.portState = "free";
+					return { kind: "free" };
+				}
+				entry.status = "conflict";
+				entry.lastError = `port ${port} is still in use after replacing pid ${own.join(", ")}`;
+				this.log(entry, "system", entry.lastError);
+				this.publishServer(entry);
+				return {
+					kind: "blocked",
+					error: entry.lastError
+				};
+			}
+			const hint = own.length > 0 ? ` — pid ${own.join(", ")} is a detached restart of this entry: set onPortConflict to "follow" to adopt it, or "reclaim" to replace it with a supervised process` : "";
+			if (entry.config.onPortConflict !== "warn") {
 				entry.status = "conflict";
-				entry.lastError = `port ${port} is already in use${suffix}`;
-				this.log(entry, "system", `${entry.lastError} — not starting (onPortConflict: block)`);
+				entry.lastError = `port ${port} is already in use${suffix}${hint}`;
+				this.log(entry, "system", `${entry.lastError} — not starting (onPortConflict: ${entry.config.onPortConflict})`);
 				this.publishServer(entry);
-				return entry.lastError;
+				return {
+					kind: "blocked",
+					error: entry.lastError
+				};
 			}
-			this.log(entry, "system", `warning: port ${port} is already in use${suffix} — starting anyway`);
-			return null;
+			this.log(entry, "system", `warning: port ${port} is already in use${suffix}${hint} — starting anyway`);
+			return { kind: "free" };
+		}
+		/**
+		* Takes over a detached successor: no spawn, no duplicate. The pid is supervised
+		* from here on (liveness, health probe, resources, stop), while its output stays
+		* wherever it was redirected.
+		*/
+		adoptEntry(entry, pid) {
+			entry.adopted = true;
+			entry.pid = pid;
+			entry.child = null;
+			entry.status = "running";
+			entry.health = entry.config.health.enabled ? "unknown" : "disabled";
+			entry.startedAt = Date.now();
+			entry.lastError = null;
+			this.log(entry, "system", `adopted pid ${pid}: a detached restart of this entry is already serving port ${entry.config.port}`);
+			this.publishServer(entry);
+			return { ok: true };
+		}
+		/** An adopted successor disappeared: fall back to the normal lifecycle. */
+		handleAdoptedExit(entry) {
+			if (entry.pid !== null) this.sampler.forget(entry.pid);
+			const ranForMs = entry.startedAt === null ? 0 : Date.now() - entry.startedAt;
+			entry.adopted = false;
+			entry.pid = null;
+			entry.resources = null;
+			entry.responseMs = null;
+			entry.exitCode = null;
+			entry.exitSignal = null;
+			this.options.history.record(entry.config.id, {
+				type: "exit",
+				detail: "adopted process exited",
+				runtimeMs: ranForMs
+			});
+			this.log(entry, "system", `the adopted process is gone after ${Math.max(1, Math.round(ranForMs / 1e3))}s`);
+			this.afterExit(entry, "adopted process exited", ranForMs, false);
 		}
 		async runBootstrap(entry) {
 			const spec = entry.config.bootstrap;
@@ -4650,6 +5304,7 @@ var init_supervisor = __esmMin((() => {
 			if (entry.pid !== null) this.sampler.forget(entry.pid);
 			entry.child = null;
 			entry.pid = null;
+			entry.adopted = false;
 			entry.resources = null;
 			entry.responseMs = null;
 			entry.exitCode = code;
@@ -4657,12 +5312,19 @@ var init_supervisor = __esmMin((() => {
 			const neverStarted = code === null && signal === null && entry.lastError !== null;
 			const detail = neverStarted ? entry.lastError : signal !== null ? `signal ${signal}` : `code ${code}`;
 			const ranForMs = entry.startedAt === null ? 0 : Date.now() - entry.startedAt;
-			const ranFor = `${Math.max(1, Math.round(ranForMs / 1e3))}s`;
 			this.options.history.record(entry.config.id, {
 				type: "exit",
 				detail,
 				runtimeMs: ranForMs
 			});
+			this.afterExit(entry, detail, ranForMs, neverStarted);
+		}
+		/**
+		* What happens once a process is gone, whether it was a child we spawned or a
+		* detached successor we adopted: back off and retry, or record the crash.
+		*/
+		afterExit(entry, detail, ranForMs, neverStarted) {
+			const ranFor = `${Math.max(1, Math.round(ranForMs / 1e3))}s`;
 			if (entry.stopping) {
 				entry.status = "stopped";
 				this.publishServer(entry);
@@ -4704,6 +5366,10 @@ var init_supervisor = __esmMin((() => {
 			await this.sampleResources(now);
 			await Promise.allSettled([...this.entries.values()].map((entry) => this.probeEntry(entry, now)));
 			for (const entry of this.entries.values()) {
+				if (entry.adopted && entry.pid !== null && !isProcessAlive(entry.pid)) {
+					this.handleAdoptedExit(entry);
+					continue;
+				}
 				if (await this.enforceMemoryLimit(entry)) continue;
 				if (this.shouldForceRestart(entry, now)) {
 					await this.restart(entry.config.id);
@@ -4715,7 +5381,7 @@ var init_supervisor = __esmMin((() => {
 		}
 		/** One scan of /proc covers every server; only live processes are sampled. */
 		async sampleResources(now) {
-			const due = [...this.entries.values()].filter((entry) => entry.pid !== null && entry.child !== null && now - entry.resourcesSampledAt >= RESOURCE_SAMPLE_INTERVAL_MS);
+			const due = [...this.entries.values()].filter((entry) => entry.pid !== null && (entry.child !== null || entry.adopted) && now - entry.resourcesSampledAt >= RESOURCE_SAMPLE_INTERVAL_MS);
 			if (due.length === 0) return;
 			for (const entry of due) entry.resourcesSampledAt = now;
 			try {
@@ -4817,6 +5483,7 @@ var init_supervisor = __esmMin((() => {
 				health: entry.health,
 				portState: entry.portState,
 				pid: entry.pid,
+				...entry.adopted ? { adopted: true } : {},
 				startedAt: entry.startedAt,
 				exitCode: entry.exitCode,
 				exitSignal: entry.exitSignal,
@@ -4867,7 +5534,9 @@ var init_supervisor = __esmMin((() => {
 				server.restarts,
 				server.nextRetryAt,
 				server.lastError,
-				server.bufferedLines
+				server.bufferedLines,
+				server.responseMs,
+				server.resources?.sampledAt
 			].join(":"))].join("|");
 			if (signature === this.lastStateSignature) return;
 			this.lastStateSignature = signature;
@@ -4957,11 +5626,15 @@ function controlBlock(configText) {
 		return null;
 	}
 }
-/** A restored config is only accepted when the full schema can read it. */
+/**
+* A restored config is accepted when this release can read it — through the same
+* tolerant parser the store uses, so an archive from a newer release keeps only
+* the keys this one understands instead of being refused outright.
+*/
 function isUsableConfig(text) {
 	if (text === null) return false;
 	try {
-		return !(configSchema(JSON.parse(text)) instanceof type.errors);
+		return parseConfig(JSON.parse(text)).config !== null;
 	} catch {
 		return false;
 	}
@@ -4974,12 +5647,9 @@ function isUsableConfig(text) {
 function archiveTargets(configText) {
 	if (configText === null) return [];
 	try {
-		const parsed = configSchema(JSON.parse(configText));
-		if (parsed instanceof type.errors) return [];
-		return resolveBackupPaths(parsed.servers.map((server) => ({
-			...server,
-			port: server.port ?? null
-		})), parsed.backups.includePaths).filter((entry) => entry.included).map((entry) => ({
+		const parsed = parseConfig(JSON.parse(configText)).config;
+		if (parsed === null) return [];
+		return resolveBackupPaths(parsed.servers, parsed.backups.includePaths).filter((entry) => entry.included).map((entry) => ({
 			path: entry.path,
 			origin: entry.origin
 		}));
@@ -5007,7 +5677,7 @@ function slugifyPath(target) {
 }
 var MANIFEST, ALLOWED_ROOTS, SUFFIX, BackupService;
 var init_backups = __esmMin((() => {
-	init_schema();
+	init_parse();
 	init_atomic();
 	init_env_file();
 	init_paths();
@@ -6552,7 +7222,7 @@ function probeHostFor(bindHost) {
 */
 async function runControlPlane(options) {
 	const existing = readRuntime();
-	if (existing !== null && existing.pid !== process.pid && isProcessAlive(existing.pid)) {
+	if (existing !== null && existing.pid !== process.pid && isProcessAlive$1(existing.pid)) {
 		logger.error(`already running (pid ${existing.pid}) at ${existing.url} — run \`home-hosted down\` first`);
 		process.exit(1);
 	}
@@ -6561,6 +7231,16 @@ async function runControlPlane(options) {
 	const store = new ConfigStore(configPath, SEED_CONFIG);
 	store.load();
 	store.writeJsonSchema();
+	if (store.configError !== null) {
+		logger.error(`refusing to start: ${store.configError}`);
+		logger.info(`fix ${store.path}, or install the release that wrote it`);
+		process.exit(1);
+	}
+	if (store.pendingMigrations.length > 0) {
+		logger.error(`refusing to start: ${store.path} needs ${store.pendingMigrations.length} migration(s) before ${appVersion()} can use it`);
+		logger.info("run `home-hosted migrate` to see and apply them");
+		process.exit(1);
+	}
 	const secrets = new SecretsStore(defaultSecretsPath);
 	const auth = new AuthService(secrets, () => store.config.control.auth);
 	const tls = new TlsStore(defaultTlsDir);
@@ -6586,7 +7266,7 @@ async function runControlPlane(options) {
 	});
 	if (!auth.passwordSet) {
 		auth.ensureDefaultPassword("hh");
-		logger.warn(`no password was set — created the default "hh"; change it in Settings → Password`);
+		logger.warn(`no password was set — created the default "hh"; change it in Settings → Authentication`);
 	}
 	const configured = store.config.control;
 	const intendedHost = options.host === void 0 ? configured.host : parseBind(options.host);
@@ -6711,14 +7391,14 @@ async function runControlPlane(options) {
 	logger.box(`home-hosted ${runtime.version}\n${endpoint.url}`);
 	logger.info(`config:  ${store.path}`);
 	logger.info(`secrets: ${secrets.path}${auth.passwordSet ? "" : " (no password set)"}`);
-	logger.info(`auth:    ${auth.isRequired() ? "required" : "disabled"}${auth.usingDefaultPassword ? " (default password)" : ""}${exposure.exposed ? " · exposed beyond loopback" : ""}`);
+	logger.info(`auth:    ${auth.isRequired() ? "required" : "disabled"}${auth.usingDefaultPassword ? " (default password)" : ""}${auth.apiTokenSet ? " · API token set" : ""}${exposure.exposed ? " · exposed beyond loopback" : ""}`);
 	logger.info(`logs:    ${store.config.logs.persist ? `${logFiles.directory} (max ${store.config.logs.maxBytes} B x ${store.config.logs.keep})` : "memory only"}`);
 	logger.info(`project: ${projectDir}`);
 	if (ui.custom) {
 		const meta = ui.status().meta;
 		logger.warn(`custom UI in use${meta === null ? "" : ` (${meta.name}${meta.version === null ? "" : ` ${meta.version}`})`} — if it breaks, run \`home-hosted ui-revert\``);
 	}
-	if (store.configError !== null) logger.warn(`config problem(s): ${store.configError}`);
+	for (const warning of store.configWarnings) logger.warn(warning);
 	for (const entry of supervisor.views()) logger.info(`  ${entry.id.padEnd(12)} ${entry.config.command} ${entry.config.args.join(" ")}`.trimEnd());
 	if (configured.openBrowser || options.open) openBrowser(endpoint.url);
 	if (options.autostart) supervisor.startAll({ autostartOnly: true }).catch((error) => {
@@ -6751,6 +7431,7 @@ var init_src = __esmMin((() => {
 	init_open();
 	init_paths();
 	init_template();
+	init_version();
 	init_port();
 	init_auth$1();
 	init_backups();
@@ -6769,6 +7450,113 @@ var init_src = __esmMin((() => {
 	packageRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
 }));
 //#endregion
+//#region src/services/init.ts
+var init_exports = /* @__PURE__ */ __exportAll({
+	PACKAGE_MANAGERS: () => PACKAGE_MANAGERS,
+	detectPackageManager: () => detectPackageManager,
+	installArgs: () => installArgs,
+	isEmptyDir: () => isEmptyDir,
+	projectGitignore: () => projectGitignore,
+	projectManifest: () => projectManifest,
+	projectScripts: () => projectScripts,
+	runCommand: () => runCommand,
+	scaffold: () => scaffold
+});
+/** The scripts every scaffolded project gets; all of them keep state inside the project. */
+function projectScripts() {
+	const withState = (args) => `home-hosted ${args} --home ./state`;
+	return {
+		"up": withState("up"),
+		"down": withState("down"),
+		"restart": withState("restart"),
+		"status": withState("status"),
+		"set-password": withState("set-password"),
+		"set-token": withState("set-token"),
+		"migrate": withState("migrate")
+	};
+}
+/** `home-hosted` is pinned to the version that wrote the project, and open to newer ones. */
+function projectManifest(name) {
+	return `${JSON.stringify({
+		name,
+		version: "0.1.0",
+		private: true,
+		description: "Servers supervised by home-hosted.",
+		type: "module",
+		engines: { node: ">=24.0.0" },
+		scripts: projectScripts(),
+		dependencies: { "home-hosted": `^${appVersion()}` }
+	}, null, 2)}\n`;
+}
+/**
+* State is generated, so it stays out — except the file that declares the servers,
+* which is the one thing worth committing.
+*/
+function projectGitignore() {
+	return `node_modules/
+
+# home-hosted: state is local, the server definitions are tracked
+state/*
+!state/servers.config.json
+data/
+`;
+}
+function isEmptyDir(dir) {
+	try {
+		return fs.readdirSync(dir).every((entry) => entry === ".git");
+	} catch {
+		return true;
+	}
+}
+function assertUsableDir(dir) {
+	let stats = null;
+	try {
+		stats = fs.statSync(dir);
+	} catch {
+		return;
+	}
+	if (!stats.isDirectory()) throw new Error(`${dir} exists and is not a directory`);
+	if (!isEmptyDir(dir)) throw new Error(`${dir} is not empty — pick another directory, or empty it first`);
+}
+/** Writes the project skeleton. Nothing is installed or initialized here. */
+function scaffold(options) {
+	const dir = path.resolve(options.dir);
+	assertUsableDir(dir);
+	const existed = fs.existsSync(dir);
+	fs.mkdirSync(dir, { recursive: true });
+	const files = [["package.json", projectManifest(options.name)], [".gitignore", projectGitignore()]];
+	for (const [name, contents] of files) fs.writeFileSync(path.join(dir, name), contents);
+	return {
+		dir,
+		created: !existed,
+		files: files.map(([name]) => name),
+		installed: false,
+		git: false
+	};
+}
+/** The package manager this machine actually has, preferring pnpm. */
+function detectPackageManager(exists) {
+	return PACKAGE_MANAGERS.find((pm) => exists(pm)) ?? "npm";
+}
+/** How to run one of the project's scripts with a given package manager. */
+function runCommand(pm, script) {
+	return pm === "npm" ? `npm run ${script}` : `${pm} run ${script}`;
+}
+/** Install arguments for a scaffolded project (the manifest already lists the dependency). */
+function installArgs(pm) {
+	return pm === "yarn" ? [] : ["install"];
+}
+var PACKAGE_MANAGERS;
+var init_init = __esmMin((() => {
+	init_version();
+	PACKAGE_MANAGERS = [
+		"pnpm",
+		"npm",
+		"yarn",
+		"bun"
+	];
+}));
+//#endregion
 //#region src/cli.ts
 /**
 * The command line. Everything here works before the state directories are known
@@ -6786,6 +7574,9 @@ Usage
   home-hosted restart [options] down, then up
   home-hosted status [--json]   is it running, where, and how to reach it
   home-hosted set-password      set the panel password without the API
+  home-hosted set-token         set the API token that scripts and agents use
+  home-hosted migrate           bring the config up to this release's schema
+  home-hosted init              scaffold a project that keeps its state in the repo
   home-hosted ui-revert         go back to the stock control panel UI
 
 Options for up/restart
@@ -6797,6 +7588,21 @@ Options for up/restart
       --foreground      run in this process instead of detaching (systemd/docker)
       --print-config    print the effective config and exit
 
+Options for set-token
+      --generate        create a strong token and print it once
+      --clear           remove the token, so it stops working
+
+Options for migrate
+      --dry-run         print what would change, write nothing
+  -y, --yes             apply without asking (or set HHOSTED_MIGRATE=allow)
+
+Options for init
+      --dir <dir>       where to scaffold (default: ./my-servers)
+      --name <name>     package name (default: the directory name)
+      --pm <manager>    pnpm | npm | yarn | bun (default: the first one installed)
+      --no-install      write the files, install nothing
+  -y, --yes             take every default, ask nothing
+
 Everywhere
       --home <dir>      state directory (default: $HHOSTED_HOME or ~/.home-hosted)
       --project <dir>   base for relative entry paths (default: the current directory)
@@ -6806,6 +7612,8 @@ Everywhere
 Environment
   HHOSTED_HOME          where config, secrets, logs, TLS and backups live
   HHOSTED_PROJECT       base for relative entry paths
+  HHOSTED_PASSWORD      the password for a non-interactive set-password
+  HHOSTED_TOKEN         the token for a non-interactive set-token
 `;
 var isTty = () => process.stdout.isTTY === true;
 var paint = (code, text) => isTty() ? `\x1B[${code}m${text}\x1B[0m` : text;
@@ -7110,6 +7918,19 @@ function formatDuration(ms) {
 	if (hours < 24) return `${hours}h ${minutes % 60}m`;
 	return `${Math.floor(hours / 24)}d ${hours % 24}h`;
 }
+/** A plain y/N question, for decisions that are not secrets. */
+function prompt(question) {
+	return new Promise((resolve) => {
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout
+		});
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer);
+		});
+	});
+}
 /** Reads a line with echo suppressed, so the password never lands in scrollback. */
 function promptHidden(question) {
 	return new Promise((resolve) => {
@@ -7132,6 +7953,165 @@ function promptHidden(question) {
 		});
 	});
 }
+/**
+* Brings `servers.config.json` up to the schema this release understands.
+*
+* Deliberately loud and deliberate: it prints every step first, backs the file up
+* before writing, refuses to write a config it cannot read, and never runs on its
+* own — a detached daemon cannot prompt, so consent comes from `--yes`, from
+* `HHOSTED_MIGRATE=allow`, or from a person at a terminal.
+*/
+async function migrateConfig(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			"config": {
+				type: "string",
+				short: "c"
+			},
+			"dry-run": { type: "boolean" },
+			"yes": {
+				type: "boolean",
+				short: "y"
+			}
+		},
+		allowPositionals: false
+	});
+	const { defaultConfigPath } = await Promise.resolve().then(() => (init_paths(), paths_exports));
+	const { applyConfigMigrations, CONFIG_SCHEMA, planConfigMigrations } = await Promise.resolve().then(() => (init_migrations(), migrations_exports));
+	const { parseConfig, stampConfig } = await Promise.resolve().then(() => (init_parse(), parse_exports));
+	const { writeFileAtomic } = await Promise.resolve().then(() => (init_atomic(), atomic_exports));
+	const { appVersion } = await Promise.resolve().then(() => (init_version(), version_exports));
+	const file = values.config ?? defaultConfigPath;
+	if (!fs.existsSync(file)) fail(`no config at ${file} — nothing to migrate`);
+	let raw;
+	try {
+		raw = JSON.parse(fs.readFileSync(file, "utf8"));
+	} catch (error) {
+		fail(`cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const meta = typeof raw.meta === "object" && raw.meta !== null ? raw.meta : {};
+	const from = typeof meta.schema === "number" ? meta.schema : CONFIG_SCHEMA;
+	const plan = planConfigMigrations(from);
+	if (plan.tooNew) fail(`${file} was written by home-hosted ${meta.writtenBy ?? "a newer release"} (config schema ${from});\n  this release understands schema ${plan.to}. Install that version, or edit the file yourself.`);
+	const stamped = stampConfig(raw);
+	const upToDate = plan.steps.length === 0;
+	if (upToDate && values["dry-run"] !== true && JSON.stringify(stamped) !== JSON.stringify(raw)) {
+		writeFileAtomic(file, `${JSON.stringify(stamped, null, 2)}\n`);
+		process.stdout.write(`${green("config stamped")} in ${file} — written by home-hosted ${appVersion()}, schema ${plan.to}\n`);
+		return;
+	}
+	if (upToDate) {
+		process.stdout.write(`config schema ${from} is already what home-hosted ${appVersion()} understands — nothing to migrate\n`);
+		return;
+	}
+	process.stdout.write(`migrating ${file}: config schema ${from} → ${plan.to}\n`);
+	for (const [index, step] of plan.steps.entries()) process.stdout.write(`  ${index + 1}. ${step.describe}\n`);
+	if (values["dry-run"] === true) {
+		process.stdout.write(`${dim(`nothing was written (--dry-run, ${plan.steps.length} step(s) pending)`)}\n`);
+		return;
+	}
+	if (!(values.yes === true || (process.env.HHOSTED_MIGRATE ?? "").toLowerCase() === "allow")) {
+		if (process.stdin.isTTY !== true) fail(`this config needs ${plan.steps.length} migration(s) and this session cannot ask.\n  re-run with --yes, or set HHOSTED_MIGRATE=allow for unattended runs`);
+		const answer = await prompt(`Apply ${plan.steps.length} migration(s) to ${path.basename(file)}? [y/N] `);
+		if (!/^yes$|^y$/i.test(answer.trim())) {
+			process.stdout.write("cancelled — nothing was written\n");
+			return;
+		}
+	}
+	const { config, applied } = applyConfigMigrations(raw, from);
+	const parsed = parseConfig(config);
+	if (parsed.config === null) fail(`the migration produced a config this release cannot read:\n  ${parsed.errors.join("\n  ")}`);
+	const backup = `${file}.bak`;
+	fs.copyFileSync(file, backup);
+	writeFileAtomic(file, `${JSON.stringify(stampConfig(config), null, 2)}\n`);
+	process.stdout.write(`${green(`migrated to schema ${plan.to}`)} (${applied.length} step(s)) in ${file}\n`);
+	process.stdout.write(`  ${dim(`previous file kept at ${backup}`)}\n`);
+	for (const key of parsed.unknownKeys) process.stdout.write(`  ${dim(`still ignoring an unrecognized key: ${key}`)}\n`);
+}
+/** Asks a yes/no question with a default, so an empty answer is a real answer. */
+async function confirm(question, fallback) {
+	const answer = (await prompt(`${question} ${fallback ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+	if (answer.length === 0) return fallback;
+	return answer === "y" || answer === "yes";
+}
+function which(command) {
+	return spawnSync(command, ["--version"], {
+		stdio: "ignore",
+		shell: process.platform === "win32"
+	}).status === 0;
+}
+/**
+* Scaffolds a project that keeps its whole setup — state, data and the server
+* definitions — inside its own directory. Interactive by nature, but `--yes`
+* takes every default so an agent or a CI job can run it unattended.
+*/
+async function initProject(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			"dir": { type: "string" },
+			"name": { type: "string" },
+			"pm": { type: "string" },
+			"no-install": { type: "boolean" },
+			"yes": {
+				type: "boolean",
+				short: "y"
+			}
+		},
+		allowPositionals: false
+	});
+	const { detectPackageManager, installArgs, PACKAGE_MANAGERS, runCommand, scaffold } = await Promise.resolve().then(() => (init_init(), init_exports));
+	const assumeYes = values.yes === true;
+	if (!assumeYes && process.stdin.isTTY !== true) fail("init needs a terminal to ask in.\n  take the defaults with: home-hosted init --yes [--dir <dir>]");
+	const defaultDir = values.dir ?? "./my-servers";
+	const dir = assumeYes ? defaultDir : (await prompt(`Project directory (${defaultDir}) `)).trim() || defaultDir;
+	const defaultName = path.basename(path.resolve(dir));
+	const name = values.name ?? (assumeYes ? defaultName : (await prompt(`Package name (${defaultName}) `)).trim() || defaultName);
+	let pm = values.pm;
+	if (pm !== void 0 && !PACKAGE_MANAGERS.includes(pm)) fail(`unknown package manager: ${pm} (expected one of ${PACKAGE_MANAGERS.join(", ")})`);
+	const detected = detectPackageManager(which);
+	if (pm === void 0) pm = assumeYes ? detected : (await prompt(`Package manager (${detected}) `)).trim() || detected;
+	const install = values["no-install"] === true ? false : assumeYes || await confirm("Install the dependencies now?", true);
+	const git = assumeYes ? which("git") : which("git") && await confirm("Initialize a git repository?", true);
+	try {
+		const result = scaffold({
+			dir,
+			name,
+			pm,
+			install,
+			git
+		});
+		process.stdout.write(`${green("project created")} in ${result.dir}\n`);
+		for (const file of result.files) process.stdout.write(`  ${dim(file)}\n`);
+	} catch (error) {
+		fail(error instanceof Error ? error.message : String(error));
+	}
+	const target = path.resolve(dir);
+	if (git) {
+		spawnSync("git", ["init", "-q"], {
+			cwd: target,
+			stdio: "inherit",
+			shell: process.platform === "win32"
+		});
+		process.stdout.write(`  ${dim("git repository initialized")}\n`);
+	}
+	if (install) {
+		process.stdout.write(`${dim(`installing with ${pm}…`)}\n`);
+		if (spawnSync(pm, installArgs(pm), {
+			cwd: target,
+			stdio: "inherit",
+			shell: process.platform === "win32"
+		}).status !== 0) process.stdout.write(`${paint("33", "install failed")} — run it yourself in ${target}\n`);
+	}
+	const relative = path.relative(process.cwd(), target);
+	const where = relative.length === 0 || relative.startsWith("..") ? target : relative;
+	const cd = relative.length === 0 ? "" : `cd ${where} && `;
+	process.stdout.write(`\nNext:\n`);
+	process.stdout.write(`  ${bold(`${cd}${runCommand(pm, "up")}`)}     start the panel (default password \`hh\`)\n`);
+	process.stdout.write(`  ${dim("then change that password under Settings → Authentication, and add your servers")}\n`);
+	process.stdout.write(`  ${dim(`${runCommand(pm, "set-token")} --generate    for scripts and agents`)}\n`);
+}
 /** Drops a user-installed UI so the stock panel serves again. */
 async function uiRevert() {
 	const { UiService } = await Promise.resolve().then(() => (init_ui(), ui_exports));
@@ -7172,6 +8152,69 @@ async function setPassword(argv) {
 	if (password.length < 8) process.stdout.write(`${dim(`"${password}" is short — easy to guess if the panel is reachable beyond loopback`)}\n`);
 	process.stdout.write(`${dim("restart the panel for it to take effect: home-hosted restart")}\n`);
 }
+/**
+* The bearer credential for scripts and agents. Unlike a session it survives a
+* restart, so an agent can set it up once and then just send the header.
+*/
+async function setToken(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			generate: { type: "boolean" },
+			clear: { type: "boolean" }
+		},
+		allowPositionals: false
+	});
+	if (values.generate === true && values.clear === true) fail("use either --generate or --clear, not both");
+	const { defaultSecretsPath } = await Promise.resolve().then(() => (init_paths(), paths_exports));
+	const { generateApiToken, SecretsStore } = await Promise.resolve().then(() => (init_secrets(), secrets_exports));
+	const store = new SecretsStore(defaultSecretsPath);
+	if (values.clear === true) {
+		if (!store.apiTokenSet) {
+			process.stdout.write("no API token is set — nothing to clear\n");
+			return;
+		}
+		store.clearApiToken();
+		process.stdout.write(`${green("API token cleared")} in ${defaultSecretsPath} — it stops working immediately\n`);
+		return;
+	}
+	let token = process.env.HHOSTED_TOKEN ?? null;
+	if (values.generate === true) token = generateApiToken();
+	else if (token === null && process.stdin.isTTY === true) token = await promptHidden("API token: ");
+	if (token !== null) token = token.trim();
+	if (token === null || token.length === 0) fail("no token given: run `home-hosted set-token --generate`, set HHOSTED_TOKEN, or paste one interactively");
+	store.setApiToken(token);
+	const generated = values.generate === true;
+	process.stdout.write(`${green(generated ? "token generated" : "token stored")} in ${defaultSecretsPath} (mode 0600)\n`);
+	if (generated) {
+		process.stdout.write(`  ${bold(token)}\n`);
+		process.stdout.write(`${dim("  shown once — only its SHA-256 is kept on disk, so copy it now")}\n`);
+	} else process.stdout.write(`${dim(`  stored as ${token.slice(0, 8)}… — the file keeps only its hash`)}\n`);
+	const { readRuntime } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
+	const runtime = readRuntime();
+	const base = (runtime?.url ?? `http://127.0.0.1:${DEFAULT_PORT}`).replace(/\/+$/, "");
+	if (runtime !== null) {
+		const verified = await verifyToken(base, token);
+		if (verified === true) process.stdout.write(`${dim(`verified: ${base}/api/auth/session accepted it`)}\n`);
+		else if (verified === false) process.stdout.write(`${dim(`the panel at ${base} did not accept it — is it running with this state directory?`)}\n`);
+	}
+	process.stdout.write(`Use it from a script or an agent:\n`);
+	process.stdout.write(`  ${bold(`curl -H "Authorization: Bearer ${generated ? token : "<token>"}" ${base}/api/state`)}\n`);
+	process.stdout.write(`${dim("It needs no restart, outlives sessions, and holds the same access as a signed-in browser.")}\n`);
+	process.stdout.write(`${dim("Remove it any time with: home-hosted set-token --clear")}\n`);
+	if (store.usingDefaultPassword) process.stdout.write(`${dim("The panel password is still the default — change it before the panel is reachable beyond loopback.")}\n`);
+}
+/** Asks the live panel whether it accepts the token, without failing when it cannot. */
+async function verifyToken(base, token) {
+	if (!base.startsWith("http://")) return null;
+	try {
+		const response = await fetch(`${base}/api/auth/session`, { headers: { authorization: `Bearer ${token}` } });
+		if (!response.ok) return false;
+		return (await response.json()).authenticated === true;
+	} catch {
+		return null;
+	}
+}
 function version() {
 	const manifest = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 	process.stdout.write(`${manifest.version ?? "0.0.0"}\n`);
@@ -7205,6 +8248,18 @@ async function main() {
 			applyDirFlags(dirFlags);
 			await setPassword(args);
 			return;
+		case "set-token":
+			applyDirFlags(dirFlags);
+			await setToken(args);
+			return;
+		case "migrate":
+			applyDirFlags(dirFlags);
+			await migrateConfig(args);
+			return;
+		case "init":
+			applyDirFlags(dirFlags);
+			await initProject(args);
+			return;
 		case "ui-revert":
 			applyDirFlags(dirFlags);
 			await uiRevert();