@floless/app 0.31.0 → 0.31.1

package/autostart.mjs

@@ -0,0 +1,251 @@
+// autostart — register/unregister FloLess to start at LOGIN via a per-user
+// "At log on" Scheduled Task (replaces the old HKCU\Run key).
+//
+// WHY a Scheduled Task and not the Run key (the bug this fixes):
+// FloLess is installed by Velopack INSIDE Claude's MSIX container — the binary
+// physically lives at
+//   %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Local\FlolessApp\…
+// (there is NO copy outside the container; %LOCALAPPDATA%\FlolessApp is just a
+// junction back into it). Explorer's logon Run-key processor silently SKIPS an
+// executable that resides inside another package's container. Verified on the
+// target machine 2026-05-30: at logon, every *other* enabled HKCU\Run entry
+// fired (Shell-Core Operational event 9707 logged OneDrive, GoogleDriveFS, …)
+// but the FloLess entry NEVER appeared — while the exact same command launches a
+// healthy server on demand (~0.8s) and via Task Scheduler (LastTaskResult 0x0).
+// It was not Fast Startup (Run keys fire fine here), not Mark-of-the-Web, not
+// Defender, not a StartupApproved disable (no such entry), and not timing (key
+// written before the boot). The single distinguishing factor is the container path.
+//
+// A per-user "At log on" Scheduled Task has none of these problems, and three
+// independent research passes (n8n / Docker / Ollama / Syncthing ecosystem +
+// Microsoft Learn) converge on it as THE mechanism for a per-user local server
+// that must come back after every reboot:
+//   • Fires on every Fast-Startup power-on — a real interactive logon always
+//     happens (Session 1 is torn down at shutdown; only the kernel session
+//     hibernates). The trap to avoid is the "At startup" trigger, which the
+//     Fast-Startup restore path skips — so we use a LOGON trigger, never a boot one.
+//   • Runs as the interactive user (InteractiveToken) → the supervisor sees the
+//     per-user license file (%LOCALAPPDATA%\FlolessApp-data) and ~/.aware. A
+//     Windows Service (LocalSystem/LocalService) would NOT — wrong profile.
+//   • Needs no admin / no UAC / no stored password (verified: Register-ScheduledTask
+//     for this user's own InteractiveToken logon task succeeds unelevated here).
+//   • Is NOT subject to the StartupApproved silent-disable that gates Run keys.
+//
+// The task's action is `"<exe>" --supervise` — the same headless, self-healing
+// watchdog as before (starts the server, respawns it within seconds if it dies).
+// Crash-recovery is the supervisor's job, NOT the autostart mechanism's (no OS
+// autostart primitive restarts a long-lived process — that's why --supervise exists).
+//
+// .mjs (not .ts) so it can be imported by BOTH main.ts (the SEA dispatcher, TS) and
+// — if ever needed — launch.mjs (plain JS), mirroring teardown.mjs / install-path.mjs.
+// Pure logic (the XML builder) is unit-tested; the imperative wrappers (schtasks.exe)
+// are exercised by the human's real Shut-Down → power-on E2E.
+import { execFileSync } from 'node:child_process';
+import { writeFileSync, rmSync, appendFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { RUN_KEY, RUN_VALUE } from './teardown.mjs';
+import { logDir, logFilePath } from './log.mjs';
+
+// Stable per-user task name (root of the user's Task Scheduler namespace: \FloLess).
+export const TASK_NAME = 'FloLess';
+
+const isWin = process.platform === 'win32';
+
+/**
+ * Is autostart a meaningful, writable setting in THIS channel? True only for the
+ * packaged SEA exe (FlolessApp.exe) on Windows — that's the only build whose logon
+ * task makes sense. The npm/dev channel runs the server via node.exe (autostart is
+ * never wired, and registering node.exe would be wrong), and autostart is Windows-only.
+ * The /api/autostart endpoint reports this as `supported`; the UI HIDES the toggle
+ * (never shows a dead control) when it's false.
+ *
+ * @param {string} [platform]  defaults to process.platform
+ * @param {string} [execPath]  defaults to process.execPath
+ * @returns {boolean}
+ */
+export function autostartSupported(platform = process.platform, execPath = process.execPath) {
+  return platform === 'win32' && /flolessapp\.exe$/i.test(execPath || '');
+}
+
+/** Minimal XML text escaping (element content + the few chars a path/user could carry). */
+function escapeXml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Build the Task Scheduler XML for the per-user logon autostart task.
+ * Pure + exported so the exact task definition is unit-tested (no side effects).
+ *
+ * @param {string} exePath  the (un-virtualized) FlolessApp.exe path to launch.
+ * @param {string} userId   the principal/trigger user, e.g. "MACHINE\\User".
+ * @returns {string} a Task Scheduler 1.2 XML document.
+ */
+export function buildAutostartTaskXml(exePath, userId) {
+  const exe = escapeXml(exePath);
+  const user = escapeXml(userId);
+  // Notes on load-bearing settings:
+  //   LogonTrigger          → fires at user logon (Fast-Startup-safe; NOT a BootTrigger).
+  //   InteractiveToken      → runs as the logged-in user with their profile loaded
+  //                           (sees the per-user license + ~/.aware); no stored password.
+  //   LeastPrivilege        → no elevation, no UAC.
+  //   ExecutionTimeLimit PT0S → never time-limit the action (default is 72h).
+  //   MultipleInstancesPolicy IgnoreNew → never stack supervisors.
+  //   battery flags false   → still start on laptops running on battery.
+  //   StartWhenAvailable    → run a missed trigger as soon as possible.
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>Keeps the FloLess local server running so your browser tab reconnects after every login.</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${user}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${user}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>false</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${exe}</Command>
+      <Arguments>--supervise</Arguments>
+    </Exec>
+  </Actions>
+</Task>`;
+}
+
+/** The current interactive user as "DOMAIN\\User" (DOMAIN falls back to the machine name). */
+function currentUserId() {
+  const dom = process.env.USERDOMAIN || process.env.COMPUTERNAME || '';
+  const user = process.env.USERNAME || '';
+  return dom ? `${dom}\\${user}` : user;
+}
+
+/** Drop the legacy HKCU\Run autostart value (the broken mechanism this replaces). Best-effort. */
+function removeLegacyRunKey() {
+  try {
+    execFileSync('reg', ['delete', RUN_KEY, '/v', RUN_VALUE, '/f'], { stdio: 'ignore', windowsHide: true });
+  } catch {
+    /* value absent — nothing to remove */
+  }
+}
+
+/**
+ * Append one diagnostic line to the server logfile, best-effort (never throws).
+ * The original Run-key autostart failed SILENTLY — that is the exact failure class
+ * this rewrite kills, so a registration failure must always leave a breadcrumb
+ * (dual-review finding, 2026-05-30) rather than vanish.
+ */
+function logLine(msg) {
+  try {
+    mkdirSync(logDir(), { recursive: true });
+    appendFileSync(logFilePath(), `${new Date().toISOString()} ${msg}\n`);
+  } catch {
+    /* logging must never crash the caller */
+  }
+}
+
+/**
+ * Register (or refresh) the per-user logon autostart task to run `"<exe>" --supervise`.
+ * Idempotent (`/F` overwrites, so this also fixes a stale path after an update).
+ * Windows-only; no-op elsewhere. Also removes the legacy Run-key value (migration).
+ *
+ * Creates the task with `schtasks.exe /Create /XML` reading a UTF-16LE temp file
+ * directly — NOT PowerShell's `Register-ScheduledTask -Xml`. schtasks is a plain
+ * Win32 exe (no ScheduledTasks PS module / execution-policy / constrained-language
+ * dependency — important on locked-down corporate machines), it reads the UTF-16LE
+ * file directly — avoiding PowerShell's `-Xml` STRING round-trip that could silently
+ * corrupt the task definition — and makes register/query/delete all one tool.
+ * (schtasks REQUIRES the UTF-16 BOM: a BOM-less file is rejected as "the task XML is
+ * malformed" — verified 2026-05-30.) Also verified: schtasks /Create of the user's
+ * own InteractiveToken logon task succeeds UNELEVATED (SUCCESS, on-demand 0x0).
+ *
+ * Throws on a schtasks failure (after logging a breadcrumb) so the best-effort
+ * callers (the Velopack install hook, ensureAutostart) decide — they swallow it,
+ * but the failure is no longer invisible.
+ */
+export function registerAutostart(exePath) {
+  if (!isWin) return;
+  const xml = buildAutostartTaskXml(exePath, currentUserId());
+  // pid + timestamp so two registrations in one process can't clobber each other's temp.
+  const tmp = join(tmpdir(), `floless-autostart-${process.pid}-${Date.now()}.xml`);
+  // BOM is REQUIRED: schtasks /Create rejects a BOM-less file as "the task XML is
+  // malformed" (it needs the U+FEFF marker to detect UTF-16). Verified 2026-05-30.
+  writeFileSync(tmp, '' + xml, { encoding: 'utf16le' });
+  try {
+    execFileSync('schtasks', ['/Create', '/TN', TASK_NAME, '/XML', tmp, '/F'], {
+      stdio: ['ignore', 'ignore', 'ignore'],
+      windowsHide: true,
+    });
+  } catch (err) {
+    logLine(`autostart: schtasks /Create failed: ${err && err.message ? err.message : err}`);
+    throw err;
+  } finally {
+    try { rmSync(tmp, { force: true }); } catch { /* temp cleanup best-effort */ }
+  }
+  removeLegacyRunKey();
+}
+
+/** True iff the autostart task exists. Uses schtasks' exit code (0 = present). Win-only. */
+export function autostartPresent() {
+  if (!isWin) return false;
+  try {
+    execFileSync('schtasks', ['/query', '/tn', TASK_NAME], { stdio: 'ignore', windowsHide: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Self-heal: ensure the autostart task exists, registering it if missing. Cheap and
+ * idempotent — called on every packaged-app open (which runs OUTSIDE Claude's MSIX
+ * container, where task registration is reliable), so the task is guaranteed present
+ * after the user opens the app even once, regardless of whether the in-container
+ * install hook could register it. Best-effort; never throws. Win-only.
+ */
+export function ensureAutostart(exePath) {
+  if (!isWin) return;
+  if (autostartPresent()) return;
+  try { registerAutostart(exePath); } catch { /* failure already logged in registerAutostart */ }
+}
+
+/** Remove the autostart task AND any legacy Run-key value. Idempotent; Win-only. */
+export function unregisterAutostart() {
+  if (!isWin) return;
+  try {
+    execFileSync('schtasks', ['/delete', '/tn', TASK_NAME, '/f'], { stdio: 'ignore', windowsHide: true });
+  } catch {
+    /* task absent — nothing to remove */
+  }
+  removeLegacyRunKey();
+}

package/dist/floless-server.cjs

@@ -52835,7 +52835,7 @@ function appVersion() {
   return resolveVersion({
     isSea: isSea2(),
     sqVersionXml: readSqVersionXml(),
-    define: true ? "0.31.0" : void 0,
+    define: true ? "0.31.1" : void 0,
     pkgVersion: readPkgVersion()
   });
 }
@@ -52845,7 +52845,7 @@ function resolveChannel(s) {
   return "dev";
 }
 function appChannel() {
-  return resolveChannel({ isSea: isSea2(), define: true ? "0.31.0" : void 0 });
+  return resolveChannel({ isSea: isSea2(), define: true ? "0.31.1" : void 0 });
 }
 
 // oauth-presets.ts

package/install-path.mjs

@@ -0,0 +1,129 @@
+// install-path — escape Claude's MSIX bind-link virtualization for paths we
+// REGISTER with Windows (Run key, floless:// handler, Scheduled Task) and for
+// the license-store directory.
+//
+// Claude desktop ships as a Windows MSIX package (`Claude_pzs8sxrjxfjjc`) that
+// virtualizes `%LOCALAPPDATA%` for processes running inside its container. A
+// Velopack install targeting `%LOCALAPPDATA%\FlolessApp\` actually lands at
+// `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Local\FlolessApp\`.
+// From INSIDE the container both paths appear via a transparent bind-link;
+// from OUTSIDE only the Packages\... path exists. So registering Windows-level
+// hooks with `process.execPath` (the apparent virtual path) makes them fail at
+// logon / from Explorer / from the browser's protocol launch with
+// ERROR_FILE_NOT_FOUND (0x80070002). The fix is to register the un-virtualized
+// REAL path. (Verified on this machine 2026-05-30: `fs.realpathSync` does NOT
+// un-virtualize — the bind-link is opaque to it — so we explicitly remap.)
+//
+// .mjs (not .ts) so launch.mjs (plain JS, shipped to npm as-is) can import it.
+// Pure functions accept dependency-injected fs helpers so they unit-test
+// without touching the real filesystem. Thin wrappers bind the real fs at the
+// edge.
+
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+
+/**
+ * @param {string} execPath  the path to (possibly) resolve.
+ * @param {string | undefined} localAppData  the `%LOCALAPPDATA%` env var (apparent value).
+ * @param {(p: string) => boolean} exists  `fs.existsSync` injection.
+ * @param {(p: string) => string[]} readdir  `fs.readdirSync` injection (Packages enumeration).
+ * @param {(p: string) => string} realpath  `fs.realpathSync` injection (may throw on failure).
+ * @returns {string} the resolved real path, or `execPath` unchanged when no remap applies.
+ */
+export function resolveRealInstallExePure(execPath, localAppData, exists, readdir, realpath) {
+  if (!execPath) return execPath;
+  // 1. realpath handles real symlinks/junctions cleanly (forward-compatible with
+  //    a future non-container install). Defensive: if realpath throws (e.g. on
+  //    a path that doesn't exist), keep the original — never block on this step.
+  let resolved = execPath;
+  try { resolved = realpath(execPath); } catch { resolved = execPath; }
+  if (resolved !== execPath) return resolved;
+
+  // 2. Container detection + remap. Only applies when execPath sits under the
+  //    apparent %LOCALAPPDATA% (i.e. we were launched from inside the container's
+  //    virtualized view). On non-Windows / non-container installs this returns
+  //    execPath unchanged.
+  if (!localAppData) return execPath;
+  // Normalize any trailing separator(s) on the env-var value before the prefix
+  // check — Windows env vars carry whatever the user/installer wrote and a
+  // trailing `\` would otherwise produce `...local\\` and silently fail to
+  // match `...Local\FlolessApp\…` (dual-review finding #3, 2026-05-30).
+  const laRoot = localAppData.replace(/[\\/]+$/, '');
+  const lcExec = execPath.toLowerCase();
+  const lcPrefix = laRoot.toLowerCase() + '\\';
+  if (!lcExec.startsWith(lcPrefix)) return execPath;
+  const tail = execPath.slice(laRoot.length); // e.g. \FlolessApp\current\FlolessApp.exe
+
+  // Already a Packages\<pkg>\LocalCache\Local\... path (i.e. the REAL location)?
+  // Don't double-map. Also handles the case where outside-container launches
+  // arrive here with the real path already.
+  if (/^\\Packages\\[^\\]+\\LocalCache\\Local\\/i.test(tail)) return execPath;
+
+  const packagesDir = `${laRoot}\\Packages`;
+  let packages;
+  try { packages = readdir(packagesDir); } catch { return execPath; }
+  if (!Array.isArray(packages)) return execPath;
+  for (const pkg of packages) {
+    const candidate = `${packagesDir}\\${pkg}\\LocalCache\\Local${tail}`;
+    if (exists(candidate)) return candidate;
+  }
+  return execPath;
+}
+
+/**
+ * Pure: if `execPath` is under an MSIX package's `\Packages\<pkg>\LocalCache\Local\`
+ * (i.e. we were launched from OUTSIDE the container at the real path), derive
+ * `<pkg>\LocalCache\Local\FlolessApp-data` as the matching license-store
+ * directory. This is how a logon Scheduled Task / Run key launch (which sees
+ * `%LOCALAPPDATA%` as the REAL user LocalAppData, not the sandbox) still finds
+ * the license file Velopack wrote into the sandbox.
+ *
+ * @param {string} execPath
+ * @returns {string | null}
+ */
+export function sandboxLicenseDirPure(execPath) {
+  if (!execPath) return null;
+  const m = execPath.match(/^(.*\\Packages\\[^\\]+\\LocalCache\\Local)\\/i);
+  return m ? `${m[1]}\\FlolessApp-data` : null;
+}
+
+// ── Real-fs wrappers ────────────────────────────────────────────────────────
+
+/**
+ * @param {string} [execPath]  defaults to `process.execPath`
+ * @returns {string}
+ */
+export function resolveRealInstallExe(execPath = process.execPath) {
+  return resolveRealInstallExePure(
+    execPath,
+    process.env.LOCALAPPDATA,
+    existsSync,
+    readdirSync,
+    realpathSync,
+  );
+}
+
+/**
+ * Side-effect: when `process.execPath` reveals we were launched from the
+ * sandbox-real path (i.e. by a logon Scheduled Task / Run key sitting outside
+ * the container), set `FLOLESS_LICENSE_DIR` to the sandbox `FlolessApp-data`
+ * dir BEFORE any module reads it. Idempotent and respectful of an
+ * already-set env var (tests + the dev workflow). No-op in dev (tsx) and
+ * for non-container installs (execPath doesn't match the Packages\… shape).
+ */
+export function deriveSandboxLicenseDir() {
+  if (process.env.FLOLESS_LICENSE_DIR) return;
+  const d = sandboxLicenseDirPure(process.execPath);
+  if (d) process.env.FLOLESS_LICENSE_DIR = d;
+}
+
+// Self-execute the side effect at module-evaluation time. ESM evaluates an
+// imported module BEFORE control returns to subsequent imports in the
+// importer, so making this top-level (rather than a call inside main.ts's
+// body) guarantees FLOLESS_LICENSE_DIR is set before licensing.ts (a
+// transitive import via main.ts → index.js) evaluates — even if some future
+// rewrite of licensing.ts reads the env var at module-load time rather than
+// lazily in storeDir(). Importing this module FIRST in main.ts preserves this
+// ordering. Idempotent + no-op when the var is already set or execPath isn't a
+// sandbox-real path, so the side effect is safe in every channel (SEA, npm,
+// tests).
+deriveSandboxLicenseDir();

package/log.mjs

@@ -0,0 +1,47 @@
+// Shared logfile location + rotation for the floless.app server. Dependency-free
+// (Node built-ins only) so BOTH launch.mjs (which routes the detached daemon's
+// stdout/stderr here) and index.ts (which records crash stacks) resolve ONE log
+// path — they must agree, or the daemon's output and the crash trace would land in
+// different files and "why did it vanish?" stays unanswerable.
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { existsSync, mkdirSync, statSync, renameSync, openSync } from 'node:fs';
+
+const MAX_BYTES = 2 * 1024 * 1024; // roll once to .1 past 2 MB
+
+// Where logs live: FLOLESS_LOG_DIR override (tests), else the licensing store's home
+// (%LocalAppData%\FlolessApp-data on Windows, ~/.aware elsewhere) under /logs.
+export function logDir() {
+  if (process.env.FLOLESS_LOG_DIR) return process.env.FLOLESS_LOG_DIR;
+  if (process.platform === 'win32' && process.env.LOCALAPPDATA) {
+    return join(process.env.LOCALAPPDATA, 'FlolessApp-data', 'logs');
+  }
+  return join(homedir(), '.aware', 'logs');
+}
+
+export function logFilePath() {
+  return join(logDir(), 'floless-server.log');
+}
+
+export function ensureLogDir() {
+  try { mkdirSync(logDir(), { recursive: true }); } catch { /* best-effort */ }
+}
+
+// Roll an oversized log to .1 (replacing any previous .1). Best-effort; never throws.
+// Safe to call from launch.mjs (before it opens the daemon's stdio fd) AND from the
+// server at startup: the second call no-ops because the file is then freshly small.
+export function rotateLog() {
+  try {
+    const p = logFilePath();
+    if (existsSync(p) && statSync(p).size > MAX_BYTES) renameSync(p, p + '.1');
+  } catch { /* best-effort */ }
+}
+
+// Open the logfile for appending (creating the dir first). Returns an fd, or null if
+// it can't be opened — the caller then falls back to 'ignore' rather than failing.
+export function openLogFd() {
+  try {
+    ensureLogDir();
+    return openSync(logFilePath(), 'a');
+  } catch { return null; }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floless/app",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "type": "module",
   "description": "Thin localhost host for floless.app — serves web/ and shells the aware CLI. No engine, no LLM.",
   "bin": {
@@ -8,8 +8,7 @@
   },
   "files": [
     "bin/",
-    "launch.mjs",
-    "teardown.mjs",
+    "*.mjs",
     "dist/",
     "package.json"
   ],

package/post-update-marker.mjs

@@ -0,0 +1,83 @@
+// One-shot, time-fresh marker signalling "the next launch is a post-self-update relaunch" (#37).
+//
+// After a Velopack self-update, Update.exe swaps current\ and relaunches FlolessApp.exe
+// **bare** → the launcher defaults to `open` → a SECOND browser tab, while the user's existing
+// tab is meant to adopt the new build in place. The marker tells cmdOpen to start the server
+// WITHOUT opening a browser; the existing tab reloads itself onto the new build (see the health
+// poll in web/aware.js).
+//
+// Two hard-won constraints shape the path + freshness:
+//
+//  1. WRITER ≠ READER, ACROSS AN MSIX BOUNDARY. The marker is dropped by the build completing
+//     the update (the updater process and/or Velopack's `--veloapp-updated` hook) and read by a
+//     DIFFERENT process (the bare relaunch's cmdOpen). In the Claude desktop install the hook
+//     runs INSIDE the MSIX container (virtualized %LOCALAPPDATA%) while the relaunch runs
+//     OUTSIDE it — so an execPath-derived path can disagree between writer and reader. We anchor
+//     the marker at ~/.floless (FLOLESS_HOME), which is OUTSIDE the virtualized LocalAppData
+//     bind-link and therefore identical in and out of the container. (We still ALSO read the
+//     legacy install-root location 0.12.1 wrote to, so an update FROM 0.12.1 is honored.)
+//
+//  2. TIME-FRESH, NOT JUST ONE-SHOT. If a marker is dropped but the relaunch never reaches
+//     cmdOpen (a failed/odd update, or Velopack writing the hook AFTER the relaunch), a stale
+//     marker must NOT silently swallow the browser on the user's next MANUAL open. Only a marker
+//     dropped within the last couple of minutes counts; either way it's consumed (deleted).
+import { existsSync, writeFileSync, rmSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const FRESH_MS = 120_000;
+
+/** Container-stable primary location (~/.floless/.post-update). FLOLESS_POST_UPDATE_MARKER overrides it (tests). */
+export function markerPath() {
+  const override = (process.env.FLOLESS_POST_UPDATE_MARKER ?? '').trim();
+  if (override) return override;
+  const root = process.env.FLOLESS_HOME ?? join(homedir(), '.floless');
+  return join(root, '.post-update');
+}
+
+/** Legacy location 0.12.1 wrote to (install root, execPath-derived). Read for back-compat. */
+function legacyMarkerPath() {
+  if ((process.env.FLOLESS_POST_UPDATE_MARKER ?? '').trim()) return null; // tests pin a single path
+  try {
+    return join(dirname(dirname(process.execPath)), '.floless-post-update');
+  } catch {
+    return null;
+  }
+}
+
+/** Best-effort: drop the one-shot marker before a self-update relaunch. Never throws. */
+export function writePostUpdateMarker() {
+  let wrote = false;
+  for (const p of [markerPath(), legacyMarkerPath()]) {
+    if (!p) continue;
+    try {
+      writeFileSync(p, new Date().toISOString());
+      wrote = true;
+    } catch {
+      /* worst case: the pre-fix extra tab — never block the update on this */
+    }
+  }
+  return wrote;
+}
+
+/**
+ * Best-effort one-shot read: returns true iff a FRESH marker existed (dropped within FRESH_MS).
+ * Always deletes any marker it finds so it fires at most once and never lingers.
+ */
+export function consumePostUpdateMarker() {
+  let fresh = false;
+  for (const p of [markerPath(), legacyMarkerPath()]) {
+    if (!p) continue;
+    try {
+      if (!existsSync(p)) continue;
+      const ageMs = Date.now() - statSync(p).mtimeMs;
+      rmSync(p, { force: true }); // consume regardless — one-shot, no lingering marker
+      // Fresh = written recently. No lower bound: a just-written file's mtime can read a few
+      // ms AHEAD of Date.now() (FS/clock granularity on Windows), which is still "recent".
+      if (ageMs < FRESH_MS) fresh = true;
+    } catch {
+      /* best-effort */
+    }
+  }
+  return fresh;
+}