@hienlh/ppm 0.23.24 → 0.23.26

package/src/services/share-host/share-host-worker.ts

@@ -0,0 +1,92 @@
+/**
+ * Share host worker — the process behind the share host's public address.
+ *
+ * The supervisor re-invokes the binary as `<bin> __share_host__ <port>`. It listens on loopback
+ * only (cloudflared, on this machine, is its only client) and answers every request through
+ * `share-host-gateway.ts`, which lets the review pages through to PPM and nothing else.
+ *
+ * Like the edge forwarder it spawns no child, so its listening socket is never inherited and its
+ * port is free again the moment it exits — which is what lets the supervisor hand a respawn the
+ * same port, keeping the connector that points at it working. `0` asks for any free port, and a
+ * preferred port that is taken falls back to one; either way the port it got is written to
+ * `.share-host-port` once it listens.
+ *
+ * It exits when its supervisor does (POSIX: the parent pid changes), so a supervisor that is
+ * replaced or killed never leaves a second one behind; on Windows the job object does the same.
+ * The parent is read from `/proc/self/stat`, not `process.ppid`: Bun reads that once at start and
+ * keeps answering the dead parent's pid after the process is reparented (measured).
+ */
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { resolveTargetPort, _resetTargetCache } from "../edge-target-resolver.ts";
+import { createLogger, installFileLogSink } from "../logger.ts";
+import { createShareHostHandler } from "./share-host-gateway.ts";
+import { SHARE_HOST_PORT_FILE } from "./share-host-config.ts";
+
+const log = createLogger("share-host");
+
+/** Above the gateway's own upstream timeout, so Bun never cuts a slow answer off first. */
+const IDLE_TIMEOUT_S = 75;
+const PARENT_CHECK_MS = 5000;
+
+export function startShareHostServer(preferredPort: number): ReturnType<typeof Bun.serve> {
+  const fetch = createShareHostHandler({ targetPort: () => resolveTargetPort(), resetTargetPort: _resetTargetCache });
+  const serve = (port: number) => Bun.serve({ hostname: "127.0.0.1", port, idleTimeout: IDLE_TIMEOUT_S, fetch });
+  try {
+    return serve(preferredPort);
+  } catch (error) {
+    if (preferredPort === 0) throw error;
+    log.warn(`Port ${preferredPort} is taken (${error}) — listening on a free one instead`);
+    return serve(0);
+  }
+}
+
+/** Whether `parent` is still this process's parent (Linux), or still exists (elsewhere). */
+function parentAlive(parent: number): boolean {
+  try {
+    const stat = readFileSync("/proc/self/stat", "utf8");
+    return Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]) === parent;
+  } catch {}
+  try {
+    process.kill(parent, 0);
+    return true;
+  } catch (e) {
+    return (e as { code?: string }).code !== "ESRCH";
+  }
+}
+
+function publishPort(port: number): void {
+  const file = SHARE_HOST_PORT_FILE();
+  const tmp = `${file}.tmp.${process.pid}`;
+  writeFileSync(tmp, String(port));
+  renameSync(tmp, file);
+}
+
+// ─── Process entry ─────────────────────────────────────────────────────
+if (process.argv.includes("__share_host__")) {
+  // Lines go to ppm.log like every other process's; the supervisor hands the log over as stderr.
+  installFileLogSink({ echo: "stderr" });
+  const idx = process.argv.indexOf("__share_host__");
+  const preferred = parseInt(process.argv[idx + 1] ?? "0", 10);
+  if (!Number.isInteger(preferred) || preferred < 0 || preferred > 65535) {
+    log.fatal(`Invalid port: ${process.argv[idx + 1]} — exiting`);
+    process.exit(2);
+  }
+
+  try {
+    const server = startShareHostServer(preferred);
+    publishPort(server.port!);
+    log.info(`Listening on 127.0.0.1:${server.port}`);
+  } catch (error) {
+    log.fatal(`Failed to listen: ${error} — exiting`);
+    process.exit(1);
+  }
+
+  if (process.platform !== "win32") {
+    const parent = process.ppid;
+    setInterval(() => {
+      if (parentAlive(parent)) return;
+      log.info("Supervisor is gone — exiting");
+      process.exit(0);
+    }, PARENT_CHECK_MS);
+  }
+}

package/src/services/slash-discovery/sdk-commands.ts

@@ -48,7 +48,7 @@ async function fetchFromSdk(projectPath: string): Promise<SlashItem[]> {
   // Loaded lazily: the CLI (`ppm skills`) uses this module's sync path only and
   // must not pull in the provider's config/database dependencies.
   const [{ query }, provider] = await Promise.all([
-    import("@anthropic-ai/claude-agent-sdk"),
+    import("../../providers/claude-cli-process-group.ts"),
     import("../../providers/claude-agent-sdk.ts"),
   ]);
 

package/src/services/supervisor-state.ts

@@ -76,7 +76,7 @@ export function writeStatus(data: Record<string, unknown>) {
 // "upgrade" is written directly by upgrade.service.ts (bypasses writeCmd, same
 // as restart.ts/stop.ts) and read by supervisor.ts's Windows poll loop — listed
 // here so the type matches what's actually read/written on disk.
-export type CmdAction = "soft_stop" | "resume" | "restart" | "retunnel" | "upgrade";
+export type CmdAction = "soft_stop" | "resume" | "restart" | "retunnel" | "reshare" | "upgrade";
 
 /** Atomically claim + read command file (rename to .claimed, read, delete) */
 export function readAndDeleteCmd(): { action: CmdAction } | null {
@@ -94,20 +94,21 @@ export function readAndDeleteCmd(): { action: CmdAction } | null {
 }
 
 /**
- * `retunnel` is the only low-priority action — it always yields to whatever
- * is already pending, since a named-tunnel reload can wait behind a genuine
- * lifecycle transition. The other three outrank it: a `resume` stuck behind
- * an unclaimed `retunnel` would otherwise leave the server looking stopped
- * (win32's poll loop is 1s; POSIX has a write/SIGUSR2 gap) for no reason.
+ * `retunnel` and `reshare` are the low-priority actions — they always yield to
+ * whatever is already pending, since a tunnel or share-host reload can wait
+ * behind a genuine lifecycle transition. The others outrank them: a `resume`
+ * stuck behind an unclaimed `retunnel` would otherwise leave the server looking
+ * stopped (win32's poll loop is 1s; POSIX has a write/SIGUSR2 gap) for no reason.
  */
 const LIFECYCLE_ACTIONS: readonly CmdAction[] = ["resume", "soft_stop", "restart", "upgrade"];
+const RELOAD_ACTIONS: readonly string[] = ["retunnel", "reshare"];
 
 /**
  * Write `.supervisor-cmd`, but never clobber a *different* action that's still
  * unclaimed — with one exception: a lifecycle action (`resume`/`soft_stop`/
- * `restart`/`upgrade`) always overwrites a pending `retunnel`. Any other
- * collision (two different lifecycle actions, or a `retunnel` behind a
- * pending lifecycle action) returns `false` without writing so the caller can
+ * `restart`/`upgrade`) always overwrites a pending `retunnel` or `reshare`. Any
+ * other collision (two different lifecycle actions, a reload behind a pending
+ * lifecycle action, or one reload behind the other) returns `false` without writing so the caller can
  * report "busy" instead of silently discarding someone else's request; a
  * warning is logged either way so a dropped command is never silent. Note:
  * `restart.ts`/`stop.ts` write this file directly and bypass this peek
@@ -119,8 +120,8 @@ export function writeCmd(action: CmdAction): boolean {
   try {
     const existing = JSON.parse(readFileSync(CMD_FILE(), "utf-8")) as { action?: string };
     if (existing?.action && existing.action !== action) {
-      const lifecycleOverridesRetunnel = LIFECYCLE_ACTIONS.includes(action) && existing.action === "retunnel";
-      if (!lifecycleOverridesRetunnel) {
+      const lifecycleOverridesReload = LIFECYCLE_ACTIONS.includes(action) && RELOAD_ACTIONS.includes(existing.action);
+      if (!lifecycleOverridesReload) {
         log.warn(`Supervisor command '${action}' dropped — '${existing.action}' still unclaimed`);
         return false;
       }
@@ -139,6 +140,21 @@ export function writeCmd(action: CmdAction): boolean {
  * the supervisor's existing 1s command-file poll loop to pick up the request.
  */
 export function requestTunnelReload(): "sent" | "busy" | "no-supervisor" {
+  return requestReload("retunnel");
+}
+
+/**
+ * Ask the running supervisor to apply changed share-host settings (`reshare`). `outdated` is a
+ * supervisor from before the share host: its dispatcher would read an unknown command as a plain
+ * SIGUSR2 and restart the server, so nothing is sent and the change waits for a restart.
+ */
+export function requestShareHostReload(): "sent" | "busy" | "no-supervisor" | "outdated" {
+  return requestReload("reshare");
+}
+
+function requestReload(action: "retunnel"): "sent" | "busy" | "no-supervisor";
+function requestReload(action: "reshare"): "sent" | "busy" | "no-supervisor" | "outdated";
+function requestReload(action: "retunnel" | "reshare"): "sent" | "busy" | "no-supervisor" | "outdated" {
   const status = readStatus();
   const pid = status.supervisorPid as number | undefined;
   if (!pid) return "no-supervisor";
@@ -151,7 +167,11 @@ export function requestTunnelReload(): "sent" | "busy" | "no-supervisor" {
     }
   }
 
-  if (!writeCmd("retunnel")) return "busy";
+  if (action === "reshare") {
+    const capabilities = Array.isArray(status.capabilities) ? (status.capabilities as unknown[]) : [];
+    if (!capabilities.includes("reshare")) return "outdated";
+  }
+  if (!writeCmd(action)) return "busy";
 
   if (process.platform !== "win32") {
     try { process.kill(pid, "SIGUSR2"); } catch { /* best-effort; poll loop is the fallback path */ }

package/src/services/supervisor.ts

@@ -29,6 +29,11 @@ import { waitForCloudflareReachable } from "./named-tunnel/network-ready.ts";
 import { decideNamedProbeAction, publicHostnameIsOurs } from "./named-tunnel/named-tunnel-probe-state.ts";
 import { isCloudflaredPid } from "./tunnel-registry.service.ts";
 import { getQuickTunnelArgs } from "./cloudflared.service.ts";
+import { ppmIngressRunArgs } from "./share-host/share-host-args.ts";
+import {
+  initShareHost, reloadShareHost, reconcileShareHost, stopShareHost, ppmConnectorRoutesByHostname,
+  routesForPpmConnector, notePpmConnectorReady, PLAIN_PPM_ROUTES, type PpmConnectorRoutes,
+} from "./share-host/share-host-supervision.ts";
 import { startStoppedPage, stopStoppedPage } from "./supervisor-stopped-page.ts";
 import { sdNotify, withoutNotifySocket } from "./sd-notify.ts";
 import {
@@ -872,16 +877,27 @@ export interface TunnelAttempt {
  * falling back to quick — or quick-only when no named config exists. Quick's
  * argv/regex are identical whichever position it takes.
  *
+ * `routes` comes from the share host (`routesForPpmConnector`). Once a review
+ * hostname has been set up, the named connector routes PPM's hostname to `port`
+ * (and, while it carries the review address, that hostname to the share host
+ * worker) by ingress rules ending in a 404, instead of `--url`, which would
+ * serve PPM on the review hostname too. The quick fallback serves PPM only.
+ *
  * Exported so a unit test can assert argv parity with `getQuickTunnelArgs`
  * against `spawnTunnel`'s actual call site, without spawning a real process.
  */
-export function buildTunnelAttempts(config: ResolvedTunnelConfig, port: number): TunnelAttempt[] {
+export function buildTunnelAttempts(
+  config: ResolvedTunnelConfig, port: number, routes: PpmConnectorRoutes = PLAIN_PPM_ROUTES,
+): TunnelAttempt[] {
   const plan = chooseTunnelSpawn(config, port);
   if (plan.mode === "quick") {
     return [{ mode: "quick", args: plan.args, regex: TUNNEL_URL_REGEX, urlFrom: "regex" }];
   }
+  const namedArgs = routes.byHostname && config.token && config.hostname
+    ? ppmIngressRunArgs(config.token, [...(routes.share ? [routes.share] : []), { hostname: config.hostname, port }])
+    : plan.args;
   return [
-    { mode: "named", args: plan.args, regex: NAMED_TUNNEL_READY_REGEX, urlFrom: "hostname" },
+    { mode: "named", args: namedArgs, regex: NAMED_TUNNEL_READY_REGEX, urlFrom: "hostname" },
     { mode: "quick", args: getQuickTunnelArgs(port), regex: TUNNEL_URL_REGEX, urlFrom: "regex" },
   ];
 }
@@ -939,7 +955,7 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
     return;
   }
 
-  const attempts = buildTunnelAttempts(namedTunnelMode, port);
+  const attempts = buildTunnelAttempts(namedTunnelMode, port, routesForPpmConnector(namedTunnelMode));
   // Only the named path pays for this: its failure costs the user their fixed
   // address, while a quick tunnel just retries with a new URL. Spawning a
   // connector before the machine's network is back is the difference between
@@ -1042,6 +1058,7 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
       ...tunnelWarningPatchForSpawnSuccess(successfulMode, downgraded),
     });
     log("INFO", `Tunnel ready: ${resolvedUrl} (PID: ${winPid}, detached${downgraded ? ", downgraded from named" : ""})`);
+    notePpmConnectorReady(winPid, successfulMode);
     await syncUrlToCloud(resolvedUrl);
     return;
   }
@@ -1135,6 +1152,7 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
     ...tunnelWarningPatchForSpawnSuccess(successfulMode, downgraded),
   });
   log("INFO", `Tunnel ready: ${resolvedUrl} (PID: ${child.pid}${downgraded ? ", downgraded from named" : ""})`);
+  notePpmConnectorReady(child.pid, successfulMode);
 
   // One-time sync of tunnel URL to cloud (WS handles periodic heartbeat)
   await syncUrlToCloud(resolvedUrl);
@@ -2019,6 +2037,7 @@ export function shutdown() {
     log("INFO", `Killing tunnel child (PID: ${tunnelChild.pid})`);
     try { tunnelChild.kill("SIGKILL"); } catch {}
   }
+  stopShareHost();
   if (adoptedTunnelPid) {
     log("INFO", `Killing adopted tunnel (PID: ${adoptedTunnelPid})`);
     try { process.kill(adoptedTunnelPid, "SIGKILL"); } catch {}
@@ -2036,6 +2055,7 @@ export function shutdown() {
 
 // ─── Main entry ────────────────────────────────────────────────────────
 export async function runSupervisor(opts: {
+  minimal?: boolean;
   port: number;
   host: string;
   profile?: string;
@@ -2078,7 +2098,7 @@ export async function runSupervisor(opts: {
       if (isAutoStartUnitStale()) {
         log("INFO", "Stale systemd unit detected — regenerating and restarting through systemd for proper process tracking");
         await enableAutoStart(
-          { port: opts.port, host: opts.host, share: opts.share, profile: opts.profile },
+          { port: opts.port, host: opts.host, share: opts.share, profile: opts.profile, minimal: opts.minimal },
           { skipStart: true },
         );
         // Schedule restart in a separate scope (survives our cgroup teardown)
@@ -2111,6 +2131,7 @@ export async function runSupervisor(opts: {
   const isUpgrade = prevStatus.state === "upgrading";
   writeStatus({
     supervisorPid: process.pid, port: opts.port, host: opts.host, availableVersion: null,
+    minimalMode: !!opts.minimal,
     state: "running", pausedAt: null, pauseReason: null, lastCrashError: null,
     pid: null,
     tunnelPid: isUpgrade ? (prevStatus.tunnelPid ?? null) : null,
@@ -2128,7 +2149,7 @@ export async function runSupervisor(opts: {
     // Unconditional (not upgrade-gated): every boot of this code understands
     // "retunnel" — its ABSENCE is how phase 3's UI detects a pre-upgrade
     // supervisor that predates the retunnel command entirely.
-    capabilities: ["retunnel"],
+    capabilities: ["retunnel", "reshare"],
     serverPort: null, // republished by the server on every spawn
   });
   // Diagnostic: a cold start (isUpgrade=false) always nulls the tunnel and forces
@@ -2143,6 +2164,7 @@ export async function runSupervisor(opts: {
     "__serve__", "0", "127.0.0.1",
     opts.profile ?? "",
   ];
+  if (opts.minimal) serverArgs.push("--minimal");
   // Strip trailing empty args
   while (serverArgs.length > 0 && serverArgs[serverArgs.length - 1] === "") serverArgs.pop();
 
@@ -2182,6 +2204,11 @@ export async function runSupervisor(opts: {
         }
         return;
       }
+      if (cmd.action === "reshare") {
+        log("INFO", "SIGUSR2: reshare command received");
+        void reloadShareHost();
+        return;
+      }
       if (cmd.action === "retunnel") {
         log("INFO", "SIGUSR2: retunnel command received");
         namedTunnelMode = await readTunnelConfigFresh();
@@ -2205,6 +2232,9 @@ export async function runSupervisor(opts: {
           log("INFO", "Tunnel switched off — tearing down the running tunnel");
           stopTunnelForDisable();
         }
+        // In `shared` mode the share host rides on this tunnel: hand it over to (or take it
+        // back from) PPM's connector, which the branch above has just restarted or stopped.
+        void reconcileShareHost({ ppmRestarting: tunnelSharingEnabled });
         // Deliberate fall-through (no return): a bare `ppm restart` sends a
         // bare SIGUSR2 with no command file of its own, and a `retunnel` that
         // happens to still be unclaimed at that instant must not silently
@@ -2365,8 +2395,13 @@ export async function runSupervisor(opts: {
             log("INFO", "Tunnel switched off — tearing down the running tunnel");
             stopTunnelForDisable();
           }
+          void reconcileShareHost({ ppmRestarting: tunnelSharingEnabled });
         });
       }
+      else if (cmd.action === "reshare") {
+        log("INFO", "Windows command: reshare");
+        void reloadShareHost();
+      }
       else if (cmd.action === "upgrade") {
         log("INFO", "Windows command: upgrade, starting self-replace");
         selfReplace().then((result) => {
@@ -2425,8 +2460,12 @@ export async function runSupervisor(opts: {
     // start with an inherited restart-once budget "spent".
     namedProbeRestartAttempted = false;
     startTunnelProbe();
-    // Try adopting tunnel kept alive from previous upgrade; spawn new if dead
-    tunnelAdopted = adoptTunnel();
+    // Try adopting tunnel kept alive from previous upgrade; spawn new if dead.
+    // Not when it routes by hostname for the review address: the previous
+    // supervisor chose those routes, the previous worker's port among them.
+    const routesByHostname = ppmConnectorRoutesByHostname(namedTunnelMode);
+    if (routesByHostname) log("INFO", "Tunnel routes the review address too — starting a fresh one with this supervisor's routes");
+    tunnelAdopted = !routesByHostname && adoptTunnel();
     if (tunnelAdopted) {
       log("INFO", "Tunnel adopted from previous instance — public URL preserved");
     } else {
@@ -2488,6 +2527,18 @@ export async function runSupervisor(opts: {
     tunnelAdopted = false;
   }
 
+  // The share host before PPM's tunnel: in `shared` mode PPM's connector routes the
+  // share hostname to the worker, so the worker's port has to be known when it spawns.
+  // After the orphan sweep above, which would otherwise take the share connector too.
+  await initShareHost({
+    logFd,
+    ppmTunnel: () => ({ config: namedTunnelMode, linkOn: tunnelSharingEnabled }),
+    restartPpmConnector: () => {
+      if (tunnelSharingEnabled) restartTunnel(_opts.port);
+    },
+    gate: withProbeSpawnGate,
+  }, prevStatus.shareHostPid, { ppmRestarting: true });
+
   // Spawn server + (fresh) tunnel in parallel
   const promises: Promise<void>[] = [spawnServer(serverArgs, logFd)];
   const tunnelLoopStarted = tunnelSharingEnabled && !tunnelAdopted;
@@ -2530,5 +2581,5 @@ if (process.argv.includes("__supervise__")) {
   const { startLogLevelSync } = await import("./log-level-config.ts");
   startLogLevelSync();
 
-  runSupervisor({ port, host, profile, share });
+  runSupervisor({ port, host, profile, share, minimal: process.argv.includes("--minimal") });
 }

package/src/services/system-metrics/ppm-protected-pids.ts

@@ -1,7 +1,7 @@
 /**
  * Which pids the kill guard must never end: the PPM server, its supervisor (or
- * plain parent), the edge forwarder, the app share tunnel and every per-port
- * preview tunnel PPM spawned.
+ * plain parent), the edge forwarder, the app share tunnel, the share host's
+ * worker and connector, and every per-port preview tunnel PPM spawned.
  *
  * `status.json` is unvalidated disk state — `supervisorPid` is only cleared by
  * a fresh supervisor start, `bun dev:server` has no supervisor at all, and dev
@@ -56,11 +56,15 @@ export function resolveProtectedPids(input: ProtectedPidsInput): ProtectedPids {
 
   const pids = new Set<number>(roots);
 
-  const edge = pidOf(status.edgePid);
-  if (edge !== null && isPpmImage(edge)) pids.add(edge);
+  for (const key of ["edgePid", "shareHostPid"]) {
+    const pid = pidOf(status[key]);
+    if (pid !== null && isPpmImage(pid)) pids.add(pid);
+  }
 
-  const tunnel = pidOf(status.tunnelPid);
-  if (tunnel !== null && cloudflared(tunnel)) pids.add(tunnel);
+  for (const key of ["tunnelPid", "shareHostTunnelPid"]) {
+    const pid = pidOf(status[key]);
+    if (pid !== null && cloudflared(pid)) pids.add(pid);
+  }
   for (const pid of input.portTunnelPids) {
     if (pid > 0 && cloudflared(pid)) pids.add(pid);
   }

package/src/services/tunnel-registry-parse.ts

@@ -134,6 +134,9 @@ export interface AppShare {
   shareUrl: string | null;
   tunnelPid: number | null;
   serverPort: number | null;
+  /** The share host's own connector (review links), which the supervisor also runs, and its address. */
+  shareHostTunnelPid?: number | null;
+  shareHostUrl?: string | null;
 }
 
 /**
@@ -150,6 +153,7 @@ export interface AppShare {
  */
 export function isAppTunnel(entry: TunnelEntry, app: AppShare): boolean {
   if (app.tunnelPid != null && entry.pid === app.tunnelPid) return true;
+  if (app.shareHostTunnelPid != null && entry.pid === app.shareHostTunnelPid) return true;
   if (app.shareUrl && entry.url && entry.url === app.shareUrl) return true;
   if (entry.source === "ppm") return false;
   if (app.serverPort != null && entry.port === app.serverPort) return true;

package/src/services/tunnel-registry.service.ts

@@ -165,16 +165,20 @@ async function recoverUrl(pid: number, metricsAddr: string | null): Promise<stri
 function readAppShare(): AppShare {
   let shareUrl: string | null = null;
   let tunnelPid: number | null = null;
+  let shareHostTunnelPid: number | null = null;
+  let shareHostUrl: string | null = null;
   try {
     const statusFile = resolve(getPpmDir(), "status.json");
     if (existsSync(statusFile)) {
       const s = JSON.parse(readFileSync(statusFile, "utf-8"));
       shareUrl = s.shareUrl ?? null;
       tunnelPid = typeof s.tunnelPid === "number" ? s.tunnelPid : null;
+      shareHostTunnelPid = typeof s.shareHostTunnelPid === "number" ? s.shareHostTunnelPid : null;
+      shareHostUrl = typeof s.shareHostUrl === "string" ? s.shareHostUrl : null;
     }
   } catch { /* ignore */ }
   const serverPort = (configService.get("port") as number | undefined) ?? null;
-  return { shareUrl, tunnelPid, serverPort };
+  return { shareUrl, tunnelPid, serverPort, shareHostTunnelPid, shareHostUrl };
 }
 
 // ---------------------------------------------------------------------------
@@ -267,7 +271,7 @@ export async function listTunnels(
     if (isAppTunnel(entry, app)) {
       entry.source = "app";
       entry.protected = true;
-      if (!entry.url) entry.url = app.shareUrl;
+      if (!entry.url) entry.url = entry.pid === app.shareHostTunnelPid ? app.shareHostUrl ?? null : app.shareUrl;
     }
   }
 

package/src/shared/design-share-types.ts

@@ -93,6 +93,11 @@ export interface DesignShareAddress {
   url: string | null;
   /** The supervisor's tunnel warning, passed through (for example, a dark named tunnel). */
   warning: string | null;
+  /**
+   * `share-host`: the review address, which reaches the review pages and nothing else of PPM
+   * (Settings → Remote Access → Review links); `ppm`: PPM's own public link.
+   */
+  via: "share-host" | "ppm";
   /** The public tunnel master switch. */
   enabled: boolean;
   /** PPM sign-in; sharing is refused while it is off. */

package/src/shared/leftover-processes.ts

@@ -0,0 +1,22 @@
+/**
+ * How long PPM lets the processes an AI chat left running outlive the chat's last activity:
+ * servers, emulators and daemons its commands started and walked away from. Shared by the
+ * server, which stops them, and Settings, which edits the number.
+ */
+
+/** Unset means this: nothing is stopped until a limit is set, only logged. */
+export const DEFAULT_LEFTOVER_IDLE_MINUTES = 0;
+/** With no limit set, the server log names what this limit would have stopped. */
+export const LOG_ONLY_IDLE_MINUTES = 30;
+/** A day: anything longer is "never", which is 0. */
+export const MAX_LEFTOVER_IDLE_MINUTES = 1440;
+
+export function isValidLeftoverIdleMinutes(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= MAX_LEFTOVER_IDLE_MINUTES;
+}
+
+/** The configured minutes, or the default when the setting is absent or unusable. 0 = never stop them. */
+export function leftoverIdleMinutes(ai: { leftover_processes_idle_minutes?: number } | undefined): number {
+  const value = ai?.leftover_processes_idle_minutes;
+  return isValidLeftoverIdleMinutes(value) ? value : DEFAULT_LEFTOVER_IDLE_MINUTES;
+}

package/src/shared/schedule-cron.ts

@@ -0,0 +1,51 @@
+/**
+ * Which cron expressions a schedule may use, for the server, the CLI and the browser alike.
+ *
+ * A prompt keeps the 5-field form (a chat turn every minute is already the most anyone wants).
+ * A script may add a seconds field in front — croner reads 6 fields that way — but may not fire
+ * more often than every {@link SCRIPT_MIN_INTERVAL_MS}: each fire spawns a process.
+ */
+import { Cron } from "croner";
+import type { ScheduleKind } from "../types/scheduler.ts";
+
+export const SCRIPT_MIN_INTERVAL_MS = 5_000;
+
+/** How many upcoming fires the interval check looks at. */
+const SAMPLE = 20;
+
+export function cronFieldCount(expr: string): number {
+  return expr.trim().split(/\s+/).filter(Boolean).length;
+}
+
+/** Why `expr` cannot drive a schedule of `kind`, or null when it can. */
+export function cronProblem(expr: string, kind: ScheduleKind): string | null {
+  const fields = cronFieldCount(expr);
+  if (kind === "prompt" && fields !== 5) {
+    return "A prompt schedule takes 5 cron fields: minute hour day month weekday";
+  }
+  if (kind === "script" && fields !== 5 && fields !== 6) {
+    return "A script schedule takes 5 cron fields, or 6 with seconds first";
+  }
+  let runs: Date[];
+  try {
+    runs = new Cron(expr).nextRuns(SAMPLE);
+  } catch (e) {
+    return `Invalid cron expression: ${(e as Error).message}`;
+  }
+  if (runs.length === 0) return "This cron expression never fires";
+  for (let i = 1; i < runs.length; i++) {
+    if (runs[i]!.getTime() - runs[i - 1]!.getTime() < SCRIPT_MIN_INTERVAL_MS) {
+      return `A schedule may fire at most every ${SCRIPT_MIN_INTERVAL_MS / 1000} seconds`;
+    }
+  }
+  return null;
+}
+
+/** The next `n` fires after `from`; empty when the expression does not parse. */
+export function nextFires(expr: string, n: number, from?: Date): Date[] {
+  try {
+    return new Cron(expr).nextRuns(n, from);
+  } catch {
+    return [];
+  }
+}