@floless/app 0.31.0 → 0.31.2

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.2" : 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.2" : void 0 });
 }
 
 // oauth-presets.ts

package/dist/web/app.css

@@ -566,6 +566,7 @@
     font-size: 12px;
     background: var(--accent-soft);
     flex-shrink: 0;
+    cursor: help;
   }
   .agent-card .fav-btn {
     position: absolute;
@@ -1124,6 +1125,10 @@
      never deletes — matching the app's other destructive affordances. */
   .modal-actions button.danger { border-color: var(--border-strong); color: var(--text); font-weight: 600; }
   .modal-actions button.danger:hover { color: var(--err); border-color: var(--err); background: rgba(248, 113, 113, 0.1); box-shadow: none; }
+  /* #125: form modal with many fields must not overflow the viewport — cap + scroll
+     the body between the pinned title and actions, mirroring .modal.routines. */
+  #form-modal .modal { max-height: 86vh; display: flex; flex-direction: column; }
+  #form-modal-body { overflow-y: auto; flex: 1 1 auto; min-height: 0; }
   .modal.library {
     width: 720px;
     max-height: 82vh;

package/dist/web/app.js

@@ -352,7 +352,7 @@ function cardEl(id, ports) {
         <div class="kind">${a.kind}</div>
         <div class="ver">${a.version}</div>
       </div>
-      <div class="icon">${a.icon}</div>
+      <div class="icon"${a.iconTip ? ` data-tip="${escapeAttr(a.iconTip)}"` : ''}>${a.icon}</div>
     </div>
     <div class="title">${a.title}</div>
     <div class="subtitle">${a.subtitle}</div>

package/dist/web/aware.js

@@ -94,10 +94,28 @@
   }
 
   const AGENT_ICONS = {
+    tekla:             '<line x1="4" y1="5" x2="20" y2="5"/><line x1="12" y1="5" x2="12" y2="20"/>',
+    file:              '<path d="M13 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V9z"/><polyline points="13 2 13 9 20 9"/>',
+    excel:             '<rect x="2" y="3" width="20" height="18" rx="2"/><line x1="12" y1="3" x2="12" y2="21"/><line x1="2" y1="12" x2="22" y2="12"/>',
+    revit:             '<rect x="3" y="4" width="18" height="17" rx="1"/><line x1="3" y1="12" x2="21" y2="12"/><line x1="12" y1="21" x2="12" y2="12"/>',
+    slack:             '<line x1="4" y1="10" x2="20" y2="10"/><line x1="4" y1="14" x2="20" y2="14"/><line x1="10" y1="4" x2="8" y2="20"/><line x1="16" y1="4" x2="14" y2="20"/>',
+    'trimble-connect': '<path d="M17.5 10a4.5 4.5 0 00-9 0A4 4 0 009 18h6a4 4 0 002.5-7z"/><line x1="12" y1="18" x2="12" y2="12"/><polyline points="9 15 12 12 15 15"/>',
+    'microsoft-365':   '<rect x="2" y="2" width="8" height="8" rx="1"/><rect x="14" y="2" width="8" height="8" rx="1"/><rect x="2" y="14" width="8" height="8" rx="1"/><rect x="14" y="14" width="8" height="8" rx="1"/>',
+    email:             '<rect x="2" y="4" width="20" height="16" rx="2"/><path d="M2 7l10 7 10-7"/>',
+    http:              '<polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/>',
+  };
+  const AGENT_NAMES = {
+    tekla: 'Tekla', file: 'File', excel: 'Excel', revit: 'Revit', slack: 'Slack',
+    'trimble-connect': 'Trimble Connect', 'microsoft-365': 'Microsoft 365', email: 'Email', http: 'HTTP',
+  };
+  const _svgWrap = (inner) => `<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${inner}</svg>`;
+  const iconFor = (agent) => _svgWrap(AGENT_ICONS[agent] || '<path d="M12 2l8 10-8 10L4 12z"/>');
+  const iconTipFor = (agent) => AGENT_NAMES[agent] || (agent ? agent.replace(/-/g, ' ') : '');
+  const AGENT_ICONS_TEXT = {
     tekla: '⊞', file: '🗀', excel: '◵', revit: '◰', slack: '✦',
     'trimble-connect': '☁', 'microsoft-365': '✉', email: '✉', http: '⇄',
   };
-  const iconFor = (agent) => AGENT_ICONS[agent] || '◈';
+  const iconTextFor = (agent) => AGENT_ICONS_TEXT[agent] || '◈';
 
   // The demo's renderChat staggers narration via setTimeout; its bootstrap call
   // (fired before this script runs) would otherwise drip stale demo lines into
@@ -289,6 +307,7 @@
     // Description tab: a plain-English explanation + a small input table that
     // EXCLUDES the code (code belongs to the Code tab, never dumped here).
     const plainDesc = execSource ? leadingComment(execSource) : '';
+    const blurbText = plainDesc && (s => s.length > 80 ? s.slice(0, 79) + '…' : s)(plainDesc.replace(/\.\s+.*/, '.').trim());
     const inputsNoCode = {};
     for (const [k, v] of Object.entries(inputs || {})) if (k !== 'code') inputsNoCode[k] = v;
     return {
@@ -296,11 +315,12 @@
       _runtimeModel: !!n.runtimeModel, // B2: lock stamped runtime-model → card badge
       _frozen: !!n.frozen, // source node carries a `frozen:` block → card badge + Unfreeze menu
       icon: iconFor(n.agent),
+      iconTip: iconTipFor(n.agent),
       kind: n.kind === 'agent' && n.agent ? `${agentLabel} agent` : escapeHtml(n.kind),
       version: pin ? `v${escapeHtml(String(pin))}` : '—',
       title: escapeHtml(n.id),
       subtitle: `${agentLabel}${cmd ? '/' + cmd : ''} · ${mode}`,
-      blurb: n.notes[0] ? escapeHtml(humanizeNote(n.notes[0].text)) : `${mode}-mode ${cmd ? '<code>' + cmd + '</code>' : escapeHtml(n.kind)} node`,
+      blurb: blurbText ? escapeHtml(blurbText) : n.notes[0] ? escapeHtml(humanizeNote(n.notes[0].text)) : `${mode}-mode ${cmd ? '<code>' + cmd + '</code>' : escapeHtml(n.kind)} node`,
       description: `${plainDesc ? `<p>${escapeHtml(plainDesc)}</p>` : ''}<p>Resolves to ${modeBadge} via <code>${escapeHtml(n.agent || n.kind)}${n.command ? '.' + escapeHtml(n.command) : ''}</code>.</p>${Object.keys(inputsNoCode).length ? `<p><strong>Inputs</strong></p>${kvTable(inputsNoCode)}` : ''}${execSource ? `<p class="dim-note">Full source in the <strong>Code</strong> tab.</p>` : ''}${notesHtml}`,
       // Rich agent/command detail when the manifest is installed (n.skill); else
       // the lock-pointer fallback below (exec/agent-less nodes, uninstalled agents).
@@ -1624,7 +1644,7 @@
     card.setAttribute('role', 'status');
 
     const status = mkEl('div', 'cred-fail-status');
-    const icon = mkEl('span', 'cred-fail-icon', iconFor(cred.id));
+    const icon = mkEl('span', 'cred-fail-icon', iconTextFor(cred.id));
     icon.setAttribute('aria-hidden', 'true');
     status.append(icon, document.createTextNode('SESSION EXPIRED'));
 
@@ -1774,6 +1794,7 @@
       const first = $body.querySelector('input:not(.fm-file-input),textarea');
       if (first) { first.focus(); if (first.select) first.select(); }
       else if (danger) $cancel.focus();
+      else $ok.focus();
       // ── images-field setup ──────────────────────────────────────────────────────
       const imageStates = new Map();
       $body.querySelectorAll('.fm-images').forEach((box) => {
@@ -2563,6 +2584,7 @@
   // popover → Update now → POST /api/update/apply, which downloads + relaunches into
   // the new version. Hidden in dev/npm (supported:false).
   const $appUpdate = document.getElementById('app-update');
+  let _appUpdateRecoveryTimer = null; // cleared before each new apply attempt
   // The apply body, extracted so the popover's "Update now" can drive it with the
   // polled target version (no textContent scrape). Preserves the npm-vs-desktop
   // branch verbatim: npm copies the command; desktop confirms → relaunch.
@@ -2578,18 +2600,32 @@
     }
     // desktop (Velopack): one-click download + relaunch
     const v = version || '';
-    if (!window.confirm('Download v' + v + ' and relaunch floless.app now?')) return;
+    const go = await formModal({ title: 'Update and relaunch', sub: 'FloLess will download v' + v + ', close, and relaunch into the new version.', fields: [], okLabel: 'Update now' });
+    if (!go) return;
     // Record the pending version so the new build's first paint can reveal the
     // what's-new panel (survives the relaunch via localStorage; cleared once shown).
     try { localStorage.setItem('floless.whatsNew.pending', v); } catch { /* private mode */ }
+    if (_appUpdateRecoveryTimer) { clearTimeout(_appUpdateRecoveryTimer); _appUpdateRecoveryTimer = null; }
     $appUpdate.disabled = true;
     $appUpdate.textContent = '↑ Updating…';
     try {
-      const r = await fetch('/api/update/apply', { method: 'POST', headers: { 'content-type': 'application/json' } });
+      const r = await fetch('/api/update/apply', { method: 'POST', headers: { 'content-type': 'application/json' }, signal: AbortSignal.timeout(5 * 60 * 1000) });
       const d = await r.json().catch(() => ({}));
       if (!r.ok || !d.ok) throw new Error(d.error || 'update failed');
       // Success: the server is exiting + Update.exe relaunches the new build. The health
       // poll flips to offline (R1 overlay), then the new version reconnects on its own.
+      // Recovery guard: if the relaunch never happens and this page stays alive (e.g. a UAC
+      // prompt was declined after the server already responded), re-enable the pill after 90 s
+      // so the user can retry — the page won't go offline in that case.
+      _appUpdateRecoveryTimer = setTimeout(() => {
+        _appUpdateRecoveryTimer = null;
+        if ($appUpdate && $appUpdate.disabled) {
+          $appUpdate.disabled = false;
+          $appUpdate.textContent = '↑ Relaunch failed — retry';
+          try { localStorage.removeItem('floless.whatsNew.pending'); } catch { /* private mode */ }
+          refreshUpdate(); // re-poll so the pill state reflects reality, same as catch path
+        }
+      }, 90_000);
     } catch (e) {
       $appUpdate.disabled = false;
       try { localStorage.removeItem('floless.whatsNew.pending'); } catch { /* private mode */ }
@@ -2667,7 +2703,8 @@
   async function applyAwareUpdate(version) {
     if (!$awareUpdate) return;
     const v = version || '';
-    if (!window.confirm('Upgrade AWARE runtime to v' + v + '? This reinstalls the npm package in place — the app stays open and the version restamps automatically.')) return;
+    const go = await formModal({ title: 'Upgrade AWARE runtime', sub: 'Reinstalls @aware-aeco/cli to v' + v + ' in place. The app stays open — the version updates automatically when the install finishes.', fields: [], okLabel: 'Upgrade now' });
+    if (!go) return;
     $awareUpdate.disabled = true;
     $awareUpdate.textContent = '↑ Upgrading…';
     try {

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.2",
   "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;
+}