oysterun 0.1.1-beta.2 → 0.1.1-beta.5

package/dev/client/web/index.html

@@ -7587,6 +7587,62 @@
                         </div>
                       </div>
                     </section>
+                    <section class="table-panel">
+                      <div class="table-title">
+                        <div class="table-title-main">
+                          <strong>Oysterun Update</strong>
+                          <div class="table-title-copy">
+                            Check and update the installed Host package.
+                          </div>
+                        </div>
+                      </div>
+                      <div class="kv-table">
+                        <div class="kv-label">Current Version</div>
+                        <div class="kv-value">
+                          <div class="mono-path" id="host-update-current">
+                            --
+                          </div>
+                        </div>
+                        <div class="kv-label">Channel</div>
+                        <div class="kv-value">
+                          <div class="mono-path" id="host-update-channel">
+                            --
+                          </div>
+                        </div>
+                        <div class="kv-label">Latest Version</div>
+                        <div class="kv-value">
+                          <div class="value-stack">
+                            <div class="mono-path" id="host-update-latest">
+                              --
+                            </div>
+                            <div class="field-hint" id="host-update-status">
+                              Click Check for updates to query npm.
+                            </div>
+                          </div>
+                        </div>
+                        <div class="kv-label">Action</div>
+                        <div class="kv-value">
+                          <div class="control-cell">
+                            <button
+                              class="btn-primary"
+                              type="button"
+                              id="host-update-check-btn"
+                              onClick=${call("checkOysterunUpdate")}
+                            >
+                              Check for updates
+                            </button>
+                            <button
+                              class="btn-primary"
+                              type="button"
+                              id="host-update-run-btn"
+                              onClick=${call("runOysterunUpdate")}
+                            >
+                              Update now
+                            </button>
+                          </div>
+                        </div>
+                      </div>
+                    </section>
                     <section
                       class="table-panel browser-notification-card"
                       id="host-notification-card"
@@ -11265,6 +11321,11 @@ Waiting for Claude login output…</pre
           loginQrError: "",
           restartLoading: false,
           restartStatus: "",
+          update: null,
+          updateChecking: false,
+          updateRunning: false,
+          updateStatus: "",
+          updateError: "",
           localUrl: "",
           defaultBrowsePath: "",
           resolvedDefaultBrowsePath: "",
@@ -26515,6 +26576,14 @@ Waiting for Claude login output…</pre
           loginQrLoading: false,
           loginQrError: "",
           restartLoading: false,
+          update:
+            data.update && typeof data.update === "object"
+              ? data.update
+              : hostPreferencesState.update,
+          updateChecking: false,
+          updateRunning: false,
+          updateStatus: "",
+          updateError: "",
           localUrl: data.local_url || "",
           defaultBrowsePath: data.default_browse_path || "",
           resolvedDefaultBrowsePath:
@@ -28099,6 +28168,50 @@ Waiting for Claude login output…</pre
             ? "Restarting..."
             : "Restart Host";
         }
+        const update = hostPreferencesState.update || {};
+        setText("host-update-current", update.current_version || "--");
+        setText("host-update-channel", update.channel || "--");
+        setText("host-update-latest", update.latest_version || "--");
+        let updateStatus =
+          hostPreferencesState.updateError ||
+          hostPreferencesState.updateStatus ||
+          update.error ||
+          "";
+        if (!updateStatus) {
+          if (update.update_available === true) {
+            updateStatus = `Update available: ${update.latest_version}.`;
+          } else if (update.latest_version) {
+            updateStatus = "Oysterun is up to date for this channel.";
+          } else if (update.update_supported === false) {
+            updateStatus =
+              "Update now is only available on the production npm Host stack.";
+          } else {
+            updateStatus = "Click Check for updates to query npm.";
+          }
+        }
+        setText("host-update-status", updateStatus);
+        const updateCheckButton = $("host-update-check-btn");
+        if (updateCheckButton) {
+          updateCheckButton.disabled =
+            disabled ||
+            hostPreferencesState.updateChecking ||
+            hostPreferencesState.updateRunning;
+          updateCheckButton.textContent = hostPreferencesState.updateChecking
+            ? "Checking..."
+            : "Check for updates";
+        }
+        const updateRunButton = $("host-update-run-btn");
+        if (updateRunButton) {
+          updateRunButton.disabled =
+            disabled ||
+            hostPreferencesState.updateChecking ||
+            hostPreferencesState.updateRunning ||
+            update.update_supported !== true ||
+            update.update_available !== true;
+          updateRunButton.textContent = hostPreferencesState.updateRunning
+            ? "Updating..."
+            : "Update now";
+        }
         const qrPanel = $("host-login-qr-panel");
         const qr = hostPreferencesState.loginQr;
         if (qrPanel) {
@@ -28314,6 +28427,98 @@ Waiting for Claude login output…</pre
         }
       }
 
+      async function checkOysterunUpdate() {
+        if (
+          hostPreferencesState.updateChecking ||
+          hostPreferencesState.updateRunning
+        ) {
+          return;
+        }
+        hostPreferencesState = {
+          ...hostPreferencesState,
+          updateChecking: true,
+          updateStatus: "Checking npm for updates...",
+          updateError: "",
+        };
+        renderHostPreferences();
+        try {
+          const data = await apiWithAuthRetry("POST", "/admin/update-check", {
+            channel: hostPreferencesState.update?.channel || null,
+          });
+          hostPreferencesState = {
+            ...hostPreferencesState,
+            update: data,
+            updateChecking: false,
+            updateStatus:
+              data.update_available === true
+                ? `Update available: ${data.latest_version}.`
+                : "Oysterun is up to date for this channel.",
+            updateError: "",
+          };
+          renderHostPreferences();
+        } catch (err) {
+          hostPreferencesState = {
+            ...hostPreferencesState,
+            updateChecking: false,
+            updateStatus: "",
+            updateError: err.message || "Could not check for updates.",
+          };
+          renderHostPreferences();
+        }
+      }
+
+      async function runOysterunUpdate() {
+        if (
+          hostPreferencesState.updateRunning ||
+          hostPreferencesState.updateChecking
+        ) {
+          return;
+        }
+        const update = hostPreferencesState.update || {};
+        if (
+          update.update_supported !== true ||
+          update.update_available !== true
+        ) {
+          return;
+        }
+        const confirmed = window.confirm(
+          "Updating Oysterun restarts the Host. Existing live runtime sessions and running loops will close; chat history remains and supported sessions can be resumed from Sessions after restart. Continue?"
+        );
+        if (!confirmed) return;
+        hostPreferencesState = {
+          ...hostPreferencesState,
+          updateRunning: true,
+          updateStatus: "Scheduling Oysterun update...",
+          updateError: "",
+        };
+        renderHostPreferences();
+        try {
+          const data = await apiWithAuthRetry("POST", "/admin/update-run", {
+            channel: update.channel || null,
+          });
+          hostPreferencesState = {
+            ...hostPreferencesState,
+            update: data,
+            updateRunning: false,
+            updateStatus:
+              "Oysterun update scheduled. Reconnect after the service comes back.",
+            updateError: "",
+          };
+          renderHostPreferences();
+          window.setTimeout(() => {
+            window.location.href = "/app/settings";
+          }, 6000);
+        } catch (err) {
+          hostPreferencesState = {
+            ...hostPreferencesState,
+            updateRunning: false,
+            updateStatus: "",
+            updateError: err.message || "Could not schedule update.",
+          };
+          renderHostPreferences();
+        }
+      }
+
       function clearHostPreferencesInput() {
         discardUnsavedHostPreferencesChanges();
       }
@@ -41361,6 +41566,8 @@ Waiting for Claude login output…</pre
       window.saveHostPreferences = saveHostPreferences;
       window.generateDirectHostLoginQr = generateDirectHostLoginQr;
       window.restartHostFromPreferences = restartHostFromPreferences;
+      window.checkOysterunUpdate = checkOysterunUpdate;
+      window.runOysterunUpdate = runOysterunUpdate;
       window.refreshWebNotificationPreferenceState =
         refreshWebNotificationPreferenceState;
       window.sendWebNotificationTest = sendWebNotificationTest;

package/docs/routec/host_setup.md

@@ -48,7 +48,9 @@ separate.
 [2/7] Host port
 2. Ask for Host port.
    - default production port is 8802.
-   - if occupied, offer the next available port.
+   - if occupied by the same managed Oysterun service, allow the selected port
+     and restart that service at the final step.
+   - if occupied by another process, offer the next available port.
 
 [3/7] iPhone connection URL
 3. Ask how the iPhone will connect to this Mac.
@@ -72,25 +74,34 @@ separate.
 9. Explain: "You need the Oysterun phone app to scan the login QR."
    Ask: "Show phone app download link and QR code?"
    - yes: show the phone app download link and QR.
-   - no: continue to the Host login QR step.
+   - no: continue to service start.
    - first version download URL: `https://oysterun.com`.
    - later production URL should be the App Store link.
 
 [6/7] Login QR
-10. Create a 15-minute one-time QR/bootstrap login token.
-11. Show the QR code in terminal.
+10. Do not print the login QR before Host start.
+11. Explain that a fresh login QR will be shown after the Host service starts.
+    If the user chooses not to start now, setup must not print a login QR.
 
 [7/7] Start Host
 12. Install the launchd service.
-13. Ask whether to start Host now, default yes.
-14. yes:
-      launchd start
+13. If no managed Oysterun service is running, ask whether to start Host now,
+    default yes.
+14. If a managed Oysterun service is already running, ask whether to restart
+    Host now, default yes.
+    - warn that existing live runtime sessions and running loops will close.
+    - explain that chat history remains and supported sessions can be resumed
+      from Sessions after restart.
+15. yes:
+      launchd start or restart
       health check
       display Web URL
       on interactive macOS setup, open `<Host URL>/app/sessions` in the browser
       after health check succeeds
+      create and print a fresh 15-minute one-time Host login QR
     no:
       print `oysterun` as the start command.
+      explain that the start command will print a fresh login QR.
 ```
 
 Setup must not ask for macOS Full Disk Access during first-run installation.
@@ -113,6 +124,11 @@ If the Host is already running and setup changes runtime connection settings,
 setup should tell the user restart is required and offer to restart through the
 service manager.
 
+Setup rerun must still go through the normal setup questions. A running Host
+does not skip port selection, password update, login QR readiness explanation,
+or the final service action. The login QR itself is only printed after the
+service starts or restarts successfully.
+
 ## Service Contract
 
 Release Host should run as a local managed service, not as a foreground
@@ -138,21 +154,24 @@ Release service behavior:
 - does not require the user to remember a raw server command
 ```
 
+`oysterun service:start` and `oysterun service:restart` must print a fresh
+15-minute one-time Host login QR at the end after the Host start/restart
+finishes successfully.
+
 ## QR Login Contract
 
 The setup QR is a convenience login/bootstrap path. It should contain enough
 information for the app to connect and log in without typing IP:port/password:
 
 ```text
-host_id
 direct_host_url
 one-time login/bootstrap token
-expiry
-Cloud API URL when Cloud direct mode is enabled
-display name
 ```
 
-The one-time token should expire after 15 minutes.
+The terminal QR should use the smallest app-compatible payload. In Stage 1 this
+is `u` for Host URL and `b` for the one-time login/bootstrap token. Host ID,
+Host display name, and expiry are product state shown or fetched separately, not
+required QR fields. The one-time token should expire after 15 minutes.
 
 Host Preferences must provide a "generate login QR" action for later pairing or
 re-login. It creates a new short-lived token and displays the QR.
@@ -240,6 +259,42 @@ settings. For settings that require process restart:
 Runtime edits must not require rebuilding the phone app. Capacitor sync/build
 is only for app code changes, not day-to-day Host/IP changes.
 
+## Host Update Control
+
+Host Preferences may expose package update controls for npm installs:
+
+```text
+current Oysterun version
+update channel, such as latest or beta
+latest version from npm registry after manual check
+Check for updates
+Update now
+```
+
+Update now is explicit. It must not run automatically on startup.
+
+First implementation:
+
+```text
+1. Owner clicks Check for updates.
+2. Host queries npm registry for the selected channel.
+3. If a newer version exists, Host enables Update now.
+4. Owner clicks Update now and confirms the restart warning.
+5. Host runs npm install -g oysterun@<channel>.
+6. Host restarts through the same service restart path.
+```
+
+Update now is supported only on the production npm Host stack. Dev/test stacks
+may show version and check status, but must not mutate the global npm package.
+
+Until runtime restore is implemented, update/restart UI must warn:
+
+```text
+Updating restarts Oysterun Host. Existing live runtime sessions and running
+loops will close; chat history remains and supported sessions can be resumed
+from Sessions after restart.
+```
+
 ## Stage 2 Direction
 
 Stage 2 may add:

package/docs/routec/npmjs_publish.md

@@ -117,12 +117,12 @@ write ~/.oysterun/config.json
 create dashboard credential hash
 register Cloud direct mode when enabled by release setup
 write Host Cloud identity state outside user-editable config
-create 15-minute one-time QR/bootstrap token
 show phone app download/QR step
-show Host login QR
+explain that Host login QR is shown after service start
 install service manager integration
 start Host by default after explicit setup flow
 wait for /health
+create and show a fresh 15-minute Host login QR only when Host starts
 show/open /app/sessions when browser open is available
 ```
 
@@ -153,6 +153,41 @@ oysterun service:logs
 Explicit service commands should fail fast when setup has not completed. They
 must not silently create config or run setup.
 
+`oysterun service:start` and `oysterun service:restart` print a fresh
+15-minute one-time Host login QR after the Host start/restart succeeds.
+
+## Update Control
+
+The npm package must support owner-visible update awareness after install.
+
+Host Preferences may show:
+
+```text
+current_version
+channel: latest or beta
+latest_version after manual npm registry check
+Check for updates
+Update now
+```
+
+Update now must be explicit and restart-aware:
+
+```text
+1. Owner clicks Update now.
+2. Host confirms that updating restarts Oysterun Host.
+3. Host runs npm install -g oysterun@<channel>.
+4. Host restarts through the release service path.
+5. Host keeps config.json, cloud_identity.json, Matrix history, and agent
+   folders untouched.
+```
+
+Update now is production-stack only. Dev/test stacks may check npm but must not
+mutate the global npm installation from Host Preferences.
+
+Until runtime restore is implemented, the update confirmation must warn that
+live runtime sessions and running loops will close, while durable chat history
+remains and supported sessions can be resumed from Sessions.
+
 ## Cloud Endpoint
 
 The production Cloud endpoint is a git-tracked product constant.

package/host-service/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oysterun-host-service",
-  "version": "0.1.1-beta.2",
+  "version": "0.1.1-beta.5",
   "type": "module",
   "description": "Oysterun host service — runs on Mac mini, manages Claude Code sessions",
   "scripts": {

package/host-service/server.mjs

@@ -4842,6 +4842,144 @@ function getActiveStackName() {
   );
 }
 
+const OYSTERUN_NPM_PACKAGE_NAME = "oysterun";
+
+function readOysterunPackageVersion() {
+  for (const packagePath of [
+    join(REPO_ROOT, "package.json"),
+    join(REPO_ROOT, "host-service", "package.json"),
+  ]) {
+    try {
+      const parsed = JSON.parse(readFileSync(packagePath, "utf-8"));
+      if (typeof parsed.version === "string" && parsed.version.trim()) {
+        return parsed.version.trim();
+      }
+    } catch {
+      // Best-effort diagnostics must not break Host Preferences.
+    }
+  }
+  return "unknown";
+}
+
+function inferOysterunUpdateChannel(version = readOysterunPackageVersion()) {
+  return String(version || "").includes("-beta") ? "beta" : "latest";
+}
+
+function normalizeOysterunUpdateChannel(value, fallback = null) {
+  const normalized = normalizeString(value || fallback);
+  if (normalized === "beta" || normalized === "latest") return normalized;
+  return inferOysterunUpdateChannel();
+}
+
+function compareVersionStrings(a, b) {
+  const normalize = (value) =>
+    String(value || "")
+      .replace(/^v/, "")
+      .split(/[-+.]/)
+      .map((part) => {
+        const number = Number.parseInt(part, 10);
+        return Number.isNaN(number) ? part : number;
+      });
+  const left = normalize(a);
+  const right = normalize(b);
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const l = left[index] ?? 0;
+    const r = right[index] ?? 0;
+    if (typeof l === "number" && typeof r === "number" && l !== r) {
+      return l > r ? 1 : -1;
+    }
+    const ls = String(l);
+    const rs = String(r);
+    if (ls !== rs) return ls > rs ? 1 : -1;
+  }
+  return 0;
+}
+
+function buildOysterunUpdateStatusPayload(extra = {}) {
+  const currentVersion = readOysterunPackageVersion();
+  const channel = normalizeOysterunUpdateChannel(extra.channel, currentVersion);
+  const latestVersion = normalizeString(extra.latest_version);
+  return {
+    status: extra.status || "update_status",
+    package_name: OYSTERUN_NPM_PACKAGE_NAME,
+    current_version: currentVersion,
+    channel,
+    latest_version: latestVersion || null,
+    update_available: latestVersion
+      ? compareVersionStrings(latestVersion, currentVersion) > 0
+      : false,
+    update_supported: getActiveStackName() === "production",
+    active_stack: getActiveStackName(),
+    checked_at: extra.checked_at || null,
+    error: extra.error || null,
+    log_path: extra.log_path || null,
+  };
+}
+
+async function checkOysterunNpmUpdate({ channel = null } = {}) {
+  const resolvedChannel = normalizeOysterunUpdateChannel(channel);
+  const resp = await fetch(
+    `https://registry.npmjs.org/${encodeURIComponent(OYSTERUN_NPM_PACKAGE_NAME)}`,
+    { headers: { Accept: "application/json" } }
+  );
+  if (!resp.ok) {
+    throw new Error(`npm registry returned HTTP ${resp.status}`);
+  }
+  const metadata = await resp.json();
+  const latestVersion = normalizeString(metadata?.["dist-tags"]?.[resolvedChannel]);
+  if (!latestVersion) {
+    throw new Error(`npm dist-tag not found: ${resolvedChannel}`);
+  }
+  return buildOysterunUpdateStatusPayload({
+    status: "update_check",
+    channel: resolvedChannel,
+    latest_version: latestVersion,
+    checked_at: new Date().toISOString(),
+  });
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function scheduleOysterunPackageUpdate({ channel = null } = {}) {
+  const stackName = getActiveStackName();
+  if (stackName !== "production") {
+    throw new Error("Oysterun package update is only available on the production npm Host stack.");
+  }
+  const resolvedChannel = normalizeOysterunUpdateChannel(channel);
+  const logDir = join(getConfigDir(), "operation_logs");
+  mkdirSync(logDir, { recursive: true });
+  const logPath = join(
+    logDir,
+    `oysterun-update-${new Date().toISOString().replace(/[:.]/g, "-")}.log`
+  );
+  const packageSpec = `${OYSTERUN_NPM_PACKAGE_NAME}@${resolvedChannel}`;
+  const command = [
+    "set -euo pipefail",
+    'export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:$PATH"',
+    `echo "[oysterun-update] start $(date -Is)"`,
+    `npm install -g ${shellQuote(packageSpec)}`,
+    `echo "[oysterun-update] npm install complete $(date -Is)"`,
+    "oysterun service:restart",
+  ].join("\n");
+  setTimeout(() => {
+    const child = spawn("bash", ["-lc", `${command} >> ${shellQuote(logPath)} 2>&1`], {
+      cwd: REPO_ROOT,
+      detached: true,
+      env: { ...process.env, OYSTERUN_RELEASE_STACK: "production" },
+      stdio: "ignore",
+    });
+    child.unref();
+  }, 500).unref();
+  return buildOysterunUpdateStatusPayload({
+    status: "update_scheduled",
+    channel: resolvedChannel,
+    log_path: logPath,
+  });
+}
+
 function scheduleHostRestart({ redirectUrl = null } = {}) {
   const stackName = getActiveStackName();
   if (!stackName) {
@@ -4918,6 +5056,7 @@ function buildHostPreferencesPayload() {
     config_path: getConfigPath(),
     config_dir: getConfigDir(),
     config_source: getConfigSource(),
+    update: buildOysterunUpdateStatusPayload(),
     ios_push: buildApnsPushStatusPayload("dashboard-admin"),
     session_defaults: config.session_defaults,
     error: null,
@@ -8146,6 +8285,45 @@ const server = createServer(async (req, res) => {
       }
     }
 
+    // ── Oysterun npm package update status/control (dashboard-authenticated) ──
+    if (req.method === "GET" && path === "/admin/update-status") {
+      if (!requireDashboardMode(claims, res)) return;
+      return respond(res, 200, buildOysterunUpdateStatusPayload());
+    }
+
+    if (req.method === "POST" && path === "/admin/update-check") {
+      if (!requireDashboardMode(claims, res)) return;
+      try {
+        const body = await readJsonBody(req);
+        return respond(
+          res,
+          200,
+          await checkOysterunNpmUpdate({ channel: body.channel })
+        );
+      } catch (err) {
+        return respond(res, 409, {
+          ...buildOysterunUpdateStatusPayload({
+            status: "update_check_failed",
+            error: err.message,
+          }),
+        });
+      }
+    }
+
+    if (req.method === "POST" && path === "/admin/update-run") {
+      if (!requireDashboardMode(claims, res)) return;
+      try {
+        const body = await readJsonBody(req);
+        return respond(
+          res,
+          202,
+          scheduleOysterunPackageUpdate({ channel: body.channel })
+        );
+      } catch (err) {
+        return respond(res, 409, { error: err.message });
+      }
+    }
+
     // ── Authenticated transcript cleanup dry-run/status APIs (P39E source only) ──
     if (
       req.method === "GET" &&

package/host-service/setup.mjs

@@ -245,16 +245,39 @@ async function promptHidden(question) {
   });
 }
 
-function runReleaseService(command, args = [], opts = {}) {
+function runReleaseService(command, args = [], opts = {}, options = {}) {
   const serviceStack = inferReleaseServiceStack(opts);
-  execFileSync(releaseServiceScript, [command, ...args], {
+  const execOptions = {
     cwd: repoRoot,
-    stdio: "inherit",
     env: {
       ...process.env,
       OYSTERUN_RELEASE_STACK: serviceStack,
     },
-  });
+  };
+  if (!options.quiet) {
+    execFileSync(releaseServiceScript, [command, ...args], {
+      ...execOptions,
+      stdio: "inherit",
+    });
+    return "";
+  }
+  try {
+    const stdout = execFileSync(releaseServiceScript, [command, ...args], {
+      ...execOptions,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return stdout || "";
+  } catch (err) {
+    const stdout = err.stdout ? String(err.stdout).trim() : "";
+    const stderr = err.stderr ? String(err.stderr).trim() : "";
+    if (stdout || stderr) {
+      console.error("  Host service diagnostic output:");
+      if (stdout) console.error(stdout);
+      if (stderr) console.error(stderr);
+    }
+    throw err;
+  }
 }
 
 function inferReleaseServiceStack(opts = {}) {
@@ -275,6 +298,55 @@ function inferReleaseServiceStack(opts = {}) {
   return "production";
 }
 
+function parseReleaseServiceStatusOutput(output) {
+  const status = {};
+  for (const line of String(output || "").split(/\r?\n/)) {
+    const match = line.match(/^([a-z_]+)=(.*)$/);
+    if (!match) continue;
+    status[match[1]] = match[2].trim();
+  }
+  return status;
+}
+
+function getReleaseServiceStatus(opts = {}) {
+  if (process.platform !== "darwin") {
+    return { available: false, running: false, status: {}, error: null };
+  }
+  try {
+    const output = runReleaseService("status", [], opts, { quiet: true });
+    const status = parseReleaseServiceStatusOutput(output);
+    const pid = status.pid && status.pid !== "-" ? status.pid : "";
+    const running =
+      status.loaded === "yes" || Boolean(pid) || status.health === "yes";
+    return { available: true, running, status, error: null };
+  } catch (err) {
+    return {
+      available: false,
+      running: false,
+      status: {},
+      error: err?.message || String(err),
+    };
+  }
+}
+
+function getUrlPort(value) {
+  try {
+    const parsed = new URL(String(value || ""));
+    if (parsed.port) return Number.parseInt(parsed.port, 10);
+    if (parsed.protocol === "https:") return 443;
+    if (parsed.protocol === "http:") return 80;
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function isPortOccupiedByManagedReleaseService(port, opts = {}) {
+  const releaseStatus = getReleaseServiceStatus(opts);
+  if (!releaseStatus.running) return false;
+  return getUrlPort(releaseStatus.status.url) === port;
+}
+
 async function maybeOpenSetupBrowser(url) {
   if (!isInteractiveSetup() || process.platform !== "darwin" || !url) return;
   try {
@@ -289,37 +361,54 @@ async function maybeOpenSetupBrowser(url) {
 
 async function maybeInstallOrStartReleaseService(opts, { hostUrl }) {
   if (!opts.installService && !opts.startService && !opts.noStartService) {
-    return false;
+    return { handled: false, started: false, serviceAlreadyRunning: false };
   }
   if (process.platform !== "darwin") {
     throw new Error("release service install/start requires macOS launchd");
   }
 
-  printSetupStep(7, "Start Host");
+  const serviceStatus = getReleaseServiceStatus(opts);
+  const serviceAlreadyRunning = serviceStatus.running === true;
+  printSetupStep(7, serviceAlreadyRunning ? "Restart Host" : "Start Host");
+  if (serviceAlreadyRunning && isInteractiveSetup()) {
+    console.log("  An Oysterun Host service is already running.");
+    console.log(
+      "  Restarting will close existing live runtime sessions and running loops."
+    );
+    console.log(
+      "  Chat history remains, and supported sessions can be resumed from Sessions after restart."
+    );
+  }
   const shouldStart = opts.noStartService
     ? false
     : opts.startService
       ? true
-      : await promptYesNoDefaultYes("Start Oysterun Host now?");
+      : await promptYesNoDefaultYes(
+          serviceAlreadyRunning
+            ? "Restart Oysterun Host now?"
+            : "Start Oysterun Host now?"
+        );
 
   console.log();
   if (shouldStart) {
     console.log(
-      `  Installing LaunchAgent and starting Oysterun Host (${inferReleaseServiceStack(opts)})...`
+      `  Installing LaunchAgent and ${serviceAlreadyRunning ? "restarting" : "starting"} Oysterun Host (${inferReleaseServiceStack(opts)})...`
     );
-    runReleaseService("install", [], opts);
+    runReleaseService("install", [], opts, { quiet: true });
     console.log(`\n  ✓ Oysterun Host is running at ${hostUrl}`);
     await maybeOpenSetupBrowser(`${hostUrl}/app/sessions`);
+    return { handled: true, started: true, serviceAlreadyRunning };
   } else {
     console.log(
       `  Installing LaunchAgent without starting Oysterun Host (${inferReleaseServiceStack(opts)})...`
     );
-    runReleaseService("install", ["--no-start"], opts);
+    runReleaseService("install", ["--no-start"], opts, { quiet: true });
     console.log("\n  Host service was installed but not started.");
     console.log("  Start later with:");
     console.log("    oysterun");
+    console.log("  A fresh login QR will be shown after the Host starts.");
+    return { handled: true, started: false, serviceAlreadyRunning };
   }
-  return true;
 }
 
 function requireNonEmptyPassword(value, label) {
@@ -390,10 +479,16 @@ async function findAvailablePort(startPort) {
   return null;
 }
 
-async function promptHostPort({ defaultPort, optsPort }) {
+async function promptHostPort({ defaultPort, optsPort, opts = {} }) {
   if (optsPort !== undefined) {
     const port = parsePortInput(optsPort);
     if (port === null) throw new Error(`Invalid port: ${optsPort}`);
+    if (
+      !(await isPortAvailable(port)) &&
+      !isPortOccupiedByManagedReleaseService(port, opts)
+    ) {
+      throw new Error(`Port ${port} is already in use`);
+    }
     return port;
   }
 
@@ -407,6 +502,12 @@ async function promptHostPort({ defaultPort, optsPort }) {
       continue;
     }
     if (await isPortAvailable(port)) return port;
+    if (isPortOccupiedByManagedReleaseService(port, opts)) {
+      console.log(
+        `  Port ${port} is used by the current Oysterun Host service and will be reused after restart.`
+      );
+      return port;
+    }
 
     const fallback = await findAvailablePort(port + 1);
     if (fallback && isInteractiveSetup()) {
@@ -625,6 +726,29 @@ function createDirectHostLoginQrPayload({ hostId, directHostUrl }) {
   };
 }
 
+function buildTerminalDirectHostLoginQrPayload(qrPayload) {
+  return {
+    u: qrPayload.verbose.direct_host_url,
+    b: qrPayload.verbose.bootstrap_token,
+  };
+}
+
+function printDirectHostLoginQr({ hostId, directHostUrl }) {
+  const qrPayload = createDirectHostLoginQrPayload({
+    hostId,
+    directHostUrl,
+  });
+  console.log("\n  Direct Host connection QR:\n");
+  qrcode.generate(
+    JSON.stringify(buildTerminalDirectHostLoginQrPayload(qrPayload)),
+    { small: true }
+  );
+  console.log(`\n  Host ID: ${hostId}`);
+  console.log(`  Direct Host URL: ${directHostUrl}`);
+  console.log(`  QR expires at: ${qrPayload.verbose.expires_at}`);
+  return qrPayload;
+}
+
 async function configureDirectMode(opts, config) {
   const detectedCommands = detectProviderCommands();
   const directSetupDefaults = getDirectSetupDefaults();
@@ -646,6 +770,7 @@ async function configureDirectMode(opts, config) {
   const port = await promptHostPort({
     defaultPort: parsePortInput(currentPort) || defaultConfig.port,
     optsPort: opts.port,
+    opts,
   });
 
   const currentPublicBaseUrl = config.public_base_url || "";
@@ -691,10 +816,10 @@ async function configureDirectMode(opts, config) {
   console.log(`  Local login username: ${dashboardUser}`);
   printDetectedProviderStatus(detectedCommands);
   console.log(`  Config saved to ${getConfigPath()}`);
-  const serviceHandled = await maybeInstallOrStartReleaseService(opts, {
+  const serviceResult = await maybeInstallOrStartReleaseService(opts, {
     hostUrl: publicBaseUrl || `http://localhost:${port}`,
   });
-  if (!serviceHandled) {
+  if (!serviceResult.handled) {
     console.log(`\n  Next steps:`);
     console.log(`    1. Run: oysterun`);
     console.log(`    2. Open the Host URL directly from your client app`);
@@ -727,6 +852,7 @@ async function configureCloudDirectMode(opts, config, backendUrl, backendStage)
   const port = await promptHostPort({
     defaultPort: parsePortInput(portValue) || defaultConfig.port,
     optsPort: opts.port,
+    opts,
   });
 
   const directHostUrl = await promptDirectHostUrl({
@@ -821,11 +947,6 @@ async function configureCloudDirectMode(opts, config, backendUrl, backendStage)
     codex_command: detectedCommands.codex_command,
   });
 
-  const qrPayload = createDirectHostLoginQrPayload({
-    hostId,
-    directHostUrl,
-  });
-
   console.log(`\n  ✓ Direct-IP Cloud Host registration complete`);
   console.log(`  Host ID: ${hostId}`);
   console.log(`  Direct Host URL: ${directHostUrl}`);
@@ -835,27 +956,34 @@ async function configureCloudDirectMode(opts, config, backendUrl, backendStage)
   printDetectedProviderStatus(detectedCommands);
   await maybeShowPhoneAppDownloadStep();
   printSetupStep(6, "Login QR");
-  console.log("\n  Direct Host connection QR:\n");
-  qrcode.generate(JSON.stringify(qrPayload.compact), { small: true });
-  console.log(`\n  QR expires at: ${qrPayload.verbose.expires_at}`);
+  console.log("  A fresh login QR will be shown after the Host service starts.");
+  console.log("  If you choose not to start now, run `oysterun` later to start and print a QR.");
   console.log(`\n  Config saved to ${getConfigPath()}`);
   console.log(`  Cloud identity saved to ${getCloudIdentityPath()}`);
-  const serviceHandled = await maybeInstallOrStartReleaseService(opts, {
+  const serviceResult = await maybeInstallOrStartReleaseService(opts, {
     hostUrl: directHostUrl,
   });
-  if (serviceHandled) {
+  if (serviceResult.started) {
+    printDirectHostLoginQr({ hostId, directHostUrl });
     console.log("\n  Oysterun is ready.");
     console.log(`  Web: ${directHostUrl}/app/sessions`);
-    console.log("  iPhone: scan the QR above, or enter the Host URL and Host password.");
+    console.log("  iPhone: scan the QR above.");
     console.log("  Later: run `oysterun`.");
+    return;
+  }
+  if (serviceResult.handled) {
+    console.log("\n  Host service was not started.");
+    console.log("  Start later with: oysterun");
+    console.log("  The start command will print a fresh login QR.");
+    return;
   }
-  if (!serviceHandled) {
+
+  if (!serviceResult.handled) {
     console.log(`\n  Next steps:`);
     console.log(`    1. Run: oysterun`);
     console.log(`    2. Connect the app to ${directHostUrl}`);
-    console.log(
-      `    3. Scan the QR within 15 minutes, or log in with the Host password`
-    );
+    console.log(`    3. Run: oysterun show-qr`);
+    console.log(`    4. Scan the QR, or log in with the Host password`);
     console.log();
   }
 }
@@ -990,15 +1118,11 @@ async function main() {
   // ── --show-qr: Re-display existing QR ──────────────────
   if (opts.showQr) {
     if (config.connection_mode === "direct" && config.host_id && config.direct_host_url) {
-      const qrPayload = createDirectHostLoginQrPayload({
+      printDirectHostLoginQr({
         hostId: config.host_id,
         directHostUrl: config.direct_host_url,
       });
-      console.log("\n  Direct Host connection QR:\n");
-      qrcode.generate(JSON.stringify(qrPayload.compact), { small: true });
-      console.log(`\n  Host ID: ${config.host_id}`);
-      console.log(`  Direct Host URL: ${config.direct_host_url}`);
-      console.log(`  QR expires at: ${qrPayload.verbose.expires_at}\n`);
+      console.log();
       return;
     }
     if (config.connection_mode !== "cloud" || !config.onboarding_url) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oysterun",
-  "version": "0.1.1-beta.2",
+  "version": "0.1.1-beta.5",
   "type": "module",
   "description": "Oysterun Host installer and local service",
   "bin": {

package/tool_scripts/oysterun_release_service.sh

@@ -26,18 +26,43 @@ for development with OYSTERUN_RELEASE_STACK=<stack>.
 EOF
 }
 
+print_login_qr_after_service_ready() {
+  local service_args=("$@")
+  local target_stack="${STACK_NAME}"
+  (
+    source "${SCRIPT_DIR}/oysterun_service_common.sh"
+    STACK_NAME="${target_stack}"
+    parse_common_args "${service_args[@]}"
+    configure_stack_runtime
+    local node_bin
+    node_bin="$(resolve_command_path node)"
+    if [[ -z "${node_bin}" ]]; then
+      echo "[oysterun-service] node not found; cannot print login QR" >&2
+      exit 1
+    fi
+    cd "${ROOT_DIR}"
+    OYSTERUN_CONFIG_DIR="${CONFIG_DIR}" \
+      OYSTERUN_PORT="${HOST_PORT}" \
+      "${node_bin}" host-service/setup.mjs --show-qr
+  ) || {
+    echo "[oysterun-service] Login QR unavailable. Run 'oysterun show-qr' after setup." >&2
+  }
+}
+
 case "${COMMAND}" in
   install)
     exec "${SCRIPT_DIR}/install_oysterun_launch_agents.sh" --stack "${STACK_NAME}" "$@"
     ;;
   start)
-    exec "${SCRIPT_DIR}/start_oysterun.sh" --stack "${STACK_NAME}" "$@"
+    "${SCRIPT_DIR}/start_oysterun.sh" --stack "${STACK_NAME}" "$@"
+    print_login_qr_after_service_ready "$@"
     ;;
   stop)
     exec "${SCRIPT_DIR}/stop_oysterun.sh" --stack "${STACK_NAME}" "$@"
     ;;
   restart)
-    exec "${SCRIPT_DIR}/restart_oysterun.sh" --stack "${STACK_NAME}" "$@"
+    "${SCRIPT_DIR}/restart_oysterun.sh" --stack "${STACK_NAME}" "$@"
+    print_login_qr_after_service_ready "$@"
     ;;
   status)
     exec "${SCRIPT_DIR}/status_oysterun_launch_agents.sh" --stack "${STACK_NAME}" "$@"