oysterun 0.1.1-beta.0 → 0.1.1-beta.2

package/bin/oysterun.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -17,6 +17,8 @@ const releaseServiceScript = join(
   "tool_scripts",
   "oysterun_release_service.sh"
 );
+const packageJsonPath = join(repoRoot, "package.json");
+const hostPackageJsonPath = join(repoRoot, "host-service", "package.json");
 
 const serviceCommands = new Map([
   ["service:install", "install"],
@@ -88,11 +90,30 @@ function inspectConfig() {
   };
 }
 
+function readPackageVersion() {
+  for (const path of [packageJsonPath, hostPackageJsonPath]) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf8"));
+      if (typeof parsed.version === "string" && parsed.version.trim()) {
+        return parsed.version.trim();
+      }
+    } catch {
+      // Keep version reporting best-effort so diagnostics never trigger setup.
+    }
+  }
+  return "unknown";
+}
+
+function printVersion() {
+  console.log(`oysterun ${readPackageVersion()}`);
+}
+
 function printHelp() {
   console.log(`Oysterun Host
 
 Usage:
   oysterun
+  oysterun --version
   oysterun setup [options]
   oysterun show-qr
   oysterun service:start
@@ -166,6 +187,11 @@ switch (command) {
   case "-h":
     printHelp();
     break;
+  case "version":
+  case "--version":
+  case "-v":
+    printVersion();
+    break;
   default:
     if (serviceCommands.has(command)) {
       runService(serviceCommands.get(command), rest);

package/dev/client/web/index.html

@@ -11275,6 +11275,7 @@ Waiting for Claude login output…</pre
           iosPush: null,
           platform: "",
           folderAccessSettingsSupported: false,
+          debugHostPreferencesFullDiskAccessBlockEnabled: false,
           folderAccessSettingsUri: "",
           defaultProvider: HOST_DEFAULT_SESSION_DEFAULTS.defaultProvider,
           effectiveDefaultProvider:
@@ -26492,6 +26493,8 @@ Waiting for Claude login output…</pre
           platform: typeof data.platform === "string" ? data.platform : "",
           folderAccessSettingsSupported:
             data.folder_access_settings_supported === true,
+          debugHostPreferencesFullDiskAccessBlockEnabled:
+            data.debug_host_preferences_full_disk_access_block_enabled === true,
           folderAccessSettingsUri:
             typeof data.folder_access_settings_uri === "string"
               ? data.folder_access_settings_uri
@@ -28144,7 +28147,9 @@ Waiting for Claude login output…</pre
         const publicUrlDisabled = disabled;
         const folderAccessVisible =
           hostPreferencesState.platform === "darwin" &&
-          hostPreferencesState.folderAccessSettingsSupported === true;
+          hostPreferencesState.folderAccessSettingsSupported === true &&
+          hostPreferencesState.debugHostPreferencesFullDiskAccessBlockEnabled ===
+            true;
         renderHostNotificationPreferences({ disabled });
         setVisible("host-folder-access-card", folderAccessVisible);
         $("host-public-base-url")?.toggleAttribute(

package/docs/routec/config_hierachy.md

@@ -193,6 +193,7 @@ Current implemented allowlist:
 | `debug_routec_facade_transcript_rotation_enabled` | `true` | Enables bounded rotation for facade transcript logs. |
 | `debug_routec_facade_transcript_max_bytes` | `262144` | Bounded facade transcript max file size. |
 | `debug_routec_facade_transcript_max_files` | `3` | Bounded facade transcript max file count. |
+| `debug_host_preferences_full_disk_access_block_enabled` | `false` | Shows the Host Preferences macOS Folder Access recovery block for debug/manual diagnosis. Hidden in normal product setup. |
 
 Behavior:
 

package/docs/routec/host_setup.md

@@ -36,19 +36,29 @@ oysterun
 ```
 
 `oysterun` enters setup automatically when required Host config is missing.
-`npm run setup` and `oysterun setup` both run the first-run wizard:
+`npm run setup` and `oysterun setup` both run the first-run wizard. Interactive
+setup questions use a step-based terminal format such as `[1/7] Host name` and
+a stable `?` prompt prefix, so explanatory copy and questions are visually
+separate.
 
 ```text
+[1/7] Host name
 1. Ask for Host display name.
+
+[2/7] Host port
 2. Ask for Host port.
    - default production port is 8802.
    - if occupied, offer the next available port.
+
+[3/7] iPhone connection URL
 3. Ask how the iPhone will connect to this Mac.
    - prefer detected Tailscale/VPN or LAN URL.
    - localhost is Mac-browser-only; for iPhone on the same Wi-Fi/LAN, use the
      Mac LAN IP address.
    - if not on the same reachable network, use Tailscale, Cloudflare Tunnel,
      VPN, or another reachable tunnel/direct URL.
+
+[4/7] Host password
 4. Ask for Host password.
    - password input must be hidden.
    - first setup must confirm password by entering it twice.
@@ -57,30 +67,36 @@ oysterun
 6. Create dashboard credential hash.
 7. Register Stage 1 direct-IP Host with Cloud when Cloud direct mode is enabled.
 8. Write Host Cloud identity to cloud_identity.json, not config.json.
-9. Ask whether the user has downloaded the Oysterun phone app.
-   - yes: continue to the Host login QR step.
-   - no: show the phone app download link and QR.
+
+[5/7] Phone app
+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.
    - 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.
-12. Ask about macOS Full Disk Access with a clear explanation:
-     Oysterun needs it to browse, preview, and let agents work with protected
-     folders such as Desktop, Documents, Downloads, external disks, or folders
-     added later.
-     If skipped, Oysterun can still start, but some file access may fail until
-     permission is granted.
-     It can be enabled later in Host Preferences > macOS Folder Access.
-13. Install the launchd service.
-14. Ask whether to start Host now, default yes.
-15. yes:
+
+[7/7] Start Host
+12. Install the launchd service.
+13. Ask whether to start Host now, default yes.
+14. yes:
       launchd start
       health check
       display Web URL
+      on interactive macOS setup, open `<Host URL>/app/sessions` in the browser
+      after health check succeeds
     no:
       print `oysterun` as the start command.
 ```
 
+Setup must not ask for macOS Full Disk Access during first-run installation.
+macOS folder access recovery UI is a Host Preferences debug block, hidden by
+default and shown only when `config.debug.json` explicitly enables it.
+
 Setup must run before the server starts. The server reads the config generated
 by setup.
 

package/host-service/config.mjs

@@ -474,6 +474,7 @@ const DEFAULT_CONFIG = Object.freeze({
   debug_routec_facade_transcript_rotation_enabled: true,
   debug_routec_facade_transcript_max_bytes: 262144,
   debug_routec_facade_transcript_max_files: 3,
+  debug_host_preferences_full_disk_access_block_enabled: false,
   debug_cloud_backend_stage: PRODUCT_CLOUD_BACKEND_STAGE,
   routec_matrix_storage_cache_enabled: true,
   transcript_retention_days: null,
@@ -494,6 +495,7 @@ const DEBUG_CONFIG_KEYS = Object.freeze([
   "debug_routec_facade_transcript_rotation_enabled",
   "debug_routec_facade_transcript_max_bytes",
   "debug_routec_facade_transcript_max_files",
+  "debug_host_preferences_full_disk_access_block_enabled",
   "debug_cloud_backend_stage",
 ]);
 const DEBUG_CONFIG_KEY_SET = new Set(DEBUG_CONFIG_KEYS);
@@ -1582,6 +1584,11 @@ function normalizeConfig(config) {
       migratedCredentialConfig.debug_routec_facade_transcript_max_files,
       DEFAULT_CONFIG.debug_routec_facade_transcript_max_files
     ),
+    debug_host_preferences_full_disk_access_block_enabled:
+      normalizeBooleanWithDefault(
+        migratedCredentialConfig.debug_host_preferences_full_disk_access_block_enabled,
+        DEFAULT_CONFIG.debug_host_preferences_full_disk_access_block_enabled
+      ),
     debug_cloud_backend_stage: normalizeCloudBackendStage(
       migratedCredentialConfig.debug_cloud_backend_stage
     ),

package/host-service/package.json

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

package/host-service/server.mjs

@@ -4889,6 +4889,8 @@ function buildHostPreferencesPayload() {
     connection_mode: CONNECTION_MODE,
     platform: process.platform,
     folder_access_settings_supported: supportsMacFolderAccessPermissions(),
+    debug_host_preferences_full_disk_access_block_enabled:
+      config.debug_host_preferences_full_disk_access_block_enabled === true,
     folder_access_settings_uri: supportsMacFolderAccessPermissions()
       ? FULL_DISK_ACCESS_SETTINGS_URI
       : null,

package/host-service/setup.mjs

@@ -40,22 +40,20 @@ import {
   createHostLoginBootstrapToken,
 } from "./host-login-bootstrap-tokens.mjs";
 import { detectProviderCommands } from "./provider-command-detection.mjs";
-import {
-  FULL_DISK_ACCESS_SETTINGS_URI,
-  openFullDiskAccessSettings,
-  supportsMacFolderAccessPermissions,
-} from "./macos-permissions.mjs";
-import { execFileSync } from "child_process";
+import { execFile, execFileSync } from "child_process";
 import { createInterface } from "readline";
 import { basename, dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 import { createServer } from "net";
 import { networkInterfaces } from "os";
+import { promisify } from "util";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const repoRoot = dirname(__dirname);
 const releaseServiceScript = join(repoRoot, "tool_scripts", "oysterun_release_service.sh");
 const OYSTERUN_PHONE_APP_DOWNLOAD_URL = "https://oysterun.com";
+const execFileAsync = promisify(execFile);
+const SETUP_TOTAL_STEPS = 7;
 
 function printDetectedProviderStatus(detectedCommands) {
   console.log("  Detected providers:");
@@ -128,9 +126,20 @@ function prompt(question) {
   });
 }
 
+function formatSetupQuestion(question) {
+  const normalized = String(question || "").trim();
+  if (normalized.startsWith("?")) return normalized;
+  return `? ${normalized}`;
+}
+
+function printSetupStep(stepNumber, title) {
+  if (!isInteractiveSetup()) return;
+  console.log(`\n[${stepNumber}/${SETUP_TOTAL_STEPS}] ${title}`);
+}
+
 async function promptWithDefault(question, defaultValue) {
   const suffix = defaultValue ? ` [${defaultValue}]` : "";
-  const answer = await prompt(`${question}${suffix}: `);
+  const answer = await prompt(`${formatSetupQuestion(question)}${suffix}: `);
   return answer || defaultValue || "";
 }
 
@@ -146,7 +155,7 @@ async function promptRequiredValue(question, defaultValue = "") {
 
 async function promptRequiredPassword(question) {
   while (true) {
-    const answer = await promptHidden(`${question}: `);
+    const answer = await promptHidden(`${formatSetupQuestion(question)}: `);
     if (answer.trim()) {
       return answer;
     }
@@ -156,13 +165,13 @@ async function promptRequiredPassword(question) {
 
 async function promptYesNoDefaultYes(question) {
   if (!process.stdin.isTTY || !process.stdout.isTTY) return true;
-  const answer = (await prompt(`${question} (Y/n) `)).trim().toLowerCase();
+  const answer = (await prompt(`${formatSetupQuestion(question)} (Y/n) `)).trim().toLowerCase();
   return !(answer === "n" || answer === "no");
 }
 
 async function promptYesNoDefaultNo(question) {
   if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
-  const answer = (await prompt(`${question} (y/N) `)).trim().toLowerCase();
+  const answer = (await prompt(`${formatSetupQuestion(question)} (y/N) `)).trim().toLowerCase();
   return answer === "y" || answer === "yes";
 }
 
@@ -172,17 +181,19 @@ function isInteractiveSetup() {
 
 async function maybeShowPhoneAppDownloadStep() {
   if (!process.stdin.isTTY || !process.stdout.isTTY) return;
-  const hasPhoneApp = await promptYesNoDefaultYes(
-    "Have you downloaded the Oysterun phone app?"
+  printSetupStep(5, "Phone app");
+  console.log("  You need the Oysterun phone app to scan the login QR.");
+  const showDownload = await promptYesNoDefaultNo(
+    "Show phone app download link and QR code?"
   );
-  if (hasPhoneApp) return;
+  if (!showDownload) return;
 
   console.log("\n  Download the Oysterun phone app first:");
   console.log(`  ${OYSTERUN_PHONE_APP_DOWNLOAD_URL}`);
   console.log("\n  App download QR:\n");
   qrcode.generate(OYSTERUN_PHONE_APP_DOWNLOAD_URL, { small: true });
   console.log("\n  This link will point to the App Store when the app is published.");
-  await prompt("  Press Enter after installing the phone app to continue to login QR...");
+  await prompt("? Press Enter after installing the phone app to continue to login QR...");
 }
 
 async function promptHidden(question) {
@@ -264,6 +275,18 @@ function inferReleaseServiceStack(opts = {}) {
   return "production";
 }
 
+async function maybeOpenSetupBrowser(url) {
+  if (!isInteractiveSetup() || process.platform !== "darwin" || !url) return;
+  try {
+    console.log(`  Opening ${url} in your browser...`);
+    await execFileAsync("open", [url]);
+    console.log("  Browser opened.");
+  } catch (err) {
+    console.log(`  Could not open the browser automatically: ${err.message}`);
+    console.log(`  Open manually: ${url}`);
+  }
+}
+
 async function maybeInstallOrStartReleaseService(opts, { hostUrl }) {
   if (!opts.installService && !opts.startService && !opts.noStartService) {
     return false;
@@ -272,6 +295,7 @@ async function maybeInstallOrStartReleaseService(opts, { hostUrl }) {
     throw new Error("release service install/start requires macOS launchd");
   }
 
+  printSetupStep(7, "Start Host");
   const shouldStart = opts.noStartService
     ? false
     : opts.startService
@@ -285,6 +309,7 @@ async function maybeInstallOrStartReleaseService(opts, { hostUrl }) {
     );
     runReleaseService("install", [], opts);
     console.log(`\n  ✓ Oysterun Host is running at ${hostUrl}`);
+    await maybeOpenSetupBrowser(`${hostUrl}/app/sessions`);
   } else {
     console.log(
       `  Installing LaunchAgent without starting Oysterun Host (${inferReleaseServiceStack(opts)})...`
@@ -373,7 +398,7 @@ async function promptHostPort({ defaultPort, optsPort }) {
   }
 
   while (true) {
-    console.log("\n  Host port");
+    printSetupStep(2, "Host port");
     console.log("  Press Enter unless this port is already used.");
     const portInput = await promptWithDefault("Host port", String(defaultPort));
     const port = parsePortInput(portInput);
@@ -502,6 +527,7 @@ async function promptDirectHostUrl({ port, existingUrl, optsUrl }) {
   }
 
   const candidates = detectHostUrlCandidates(port, existingUrl);
+  printSetupStep(3, "iPhone connection URL");
   console.log("\n  How will your iPhone connect to this Mac?");
   console.log("\n  We detected:");
   candidates.forEach((candidate, index) => {
@@ -532,7 +558,7 @@ async function promptDirectHostUrl({ port, existingUrl, optsUrl }) {
     console.log(`  Press Enter only if you are setting up Mac-browser access for now.`);
     while (true) {
       const answer = await prompt(
-        `Host URL for iPhone login (or Enter for http://localhost:${port}): `
+        `${formatSetupQuestion(`Host URL for iPhone login (or Enter for http://localhost:${port})`)}: `
       );
       const trimmed = answer.trim();
       if (!trimmed) return `http://localhost:${port}`;
@@ -545,7 +571,7 @@ async function promptDirectHostUrl({ port, existingUrl, optsUrl }) {
   const selectedDefault = defaultIndex >= 0 ? defaultIndex + 1 : 1;
   while (true) {
     const answer = await prompt(
-      `Choose Host URL [${selectedDefault}] or paste a different URL: `
+      `${formatSetupQuestion(`Choose Host URL [${selectedDefault}] or paste a different URL`)}: `
     );
     const trimmed = answer.trim();
     if (!trimmed) return candidates[selectedDefault - 1].url;
@@ -563,47 +589,6 @@ async function promptDirectHostUrl({ port, existingUrl, optsUrl }) {
   }
 }
 
-async function maybeOfferMacFolderAccessPermissionDuringSetup() {
-  if (!supportsMacFolderAccessPermissions()) return;
-  if (!process.stdin.isTTY || !process.stdout.isTTY) return;
-  console.log();
-  console.log(
-    "Oysterun agents can only work with files macOS allows this Host to read."
-  );
-  console.log(
-    "Enable Full Disk Access if you want agents to browse, preview, read, or write files in Desktop, Documents, Downloads, external disks, or project folders you add later."
-  );
-  console.log(
-    "You can skip now. Chat still works, but file browsing or agent file tasks may fail until permission is granted."
-  );
-  console.log(
-    "You can enable this later in Host Preferences > macOS Folder Access."
-  );
-  const answer = await prompt(
-    "Open System Settings > Privacy & Security > Full Disk Access now? (y/N) "
-  );
-  if (answer.trim().toLowerCase() !== "y") {
-    console.log("  Skipped Full Disk Access setup.");
-    console.log(
-      "  You can enable it later from Host Preferences > macOS Folder Access."
-    );
-    return;
-  }
-  try {
-    await openFullDiskAccessSettings();
-    console.log("  Opened System Settings to Full Disk Access.");
-    console.log(`  If it does not appear automatically, open: ${FULL_DISK_ACCESS_SETTINGS_URI}`);
-  } catch (err) {
-    console.log(`  Could not open System Settings automatically: ${err.message}`);
-    console.log(
-      "  Open System Settings > Privacy & Security > Full Disk Access, then enable Oysterun."
-    );
-    console.log(
-      "  You can also retry later from Host Preferences > macOS Folder Access."
-    );
-  }
-}
-
 function clearCloudRegistration() {
   return {
     connection_mode: "direct",
@@ -651,7 +636,8 @@ async function configureDirectMode(opts, config) {
   }
   const displayNameRaw = opts.displayName !== undefined
     ? opts.displayName
-    : (console.log("\n  This name appears in the iPhone app Host list."),
+    : (printSetupStep(1, "Host name"),
+      console.log("  This name appears in the iPhone app Host list."),
       await promptWithDefault("Name this Host", currentDisplayName));
   const displayName = displayNameRaw.trim() || null;
   const currentPort = String(
@@ -705,7 +691,6 @@ async function configureDirectMode(opts, config) {
   console.log(`  Local login username: ${dashboardUser}`);
   printDetectedProviderStatus(detectedCommands);
   console.log(`  Config saved to ${getConfigPath()}`);
-  await maybeOfferMacFolderAccessPermissionDuringSetup();
   const serviceHandled = await maybeInstallOrStartReleaseService(opts, {
     hostUrl: publicBaseUrl || `http://localhost:${port}`,
   });
@@ -728,7 +713,8 @@ async function configureCloudDirectMode(opts, config, backendUrl, backendStage)
   }
   const displayNameDefault = config.display_name || directSetupDefaults.display_name;
   if (isInteractiveSetup()) {
-    console.log("\n  This name appears in the iPhone app Host list.");
+    printSetupStep(1, "Host name");
+    console.log("  This name appears in the iPhone app Host list.");
   }
   const displayName = (
     opts.displayName !== undefined
@@ -757,6 +743,7 @@ async function configureCloudDirectMode(opts, config, backendUrl, backendStage)
     throw new Error("Direct Host URL required");
   }
 
+  printSetupStep(4, "Host password");
   const hasExistingPasswordHash = typeof config.dashboard_password_hash === "string" && config.dashboard_password_hash.trim().length > 0;
   let dashboardPasswordHash = config.dashboard_password_hash || null;
   const hostPassword = opts.hostPassword !== undefined
@@ -847,12 +834,12 @@ async function configureCloudDirectMode(opts, config, backendUrl, backendStage)
   console.log(`  Local login user: admin`);
   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(`\n  Config saved to ${getConfigPath()}`);
   console.log(`  Cloud identity saved to ${getCloudIdentityPath()}`);
-  await maybeOfferMacFolderAccessPermissionDuringSetup();
   const serviceHandled = await maybeInstallOrStartReleaseService(opts, {
     hostUrl: directHostUrl,
   });
@@ -975,12 +962,12 @@ async function configureCloudMode(opts, config, backendUrl, backendStage) {
   printDetectedProviderStatus(detectedCommands);
 
   await maybeShowPhoneAppDownloadStep();
+  printSetupStep(6, "Login QR");
   console.log("\n  Scan this QR code with the Oysterun app to claim your farm:\n");
   qrcode.generate(data.onboarding_url, { small: true });
 
   console.log(`\n  Config saved to ${getConfigPath()}`);
   console.log(`  Cloud identity saved to ${getCloudIdentityPath()}`);
-  await maybeOfferMacFolderAccessPermissionDuringSetup();
   console.log(`\n  Next steps:`);
   console.log(`    1. Scan the QR code above with the Oysterun app`);
   console.log(`    2. Run: oysterun`);

package/package.json

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