@openparachute/hub 0.6.3-rc.3 → 0.6.3

package/src/account-home-ui.ts

@@ -174,6 +174,15 @@ export function renderAccountHome(opts: RenderAccountHomeOpts): string {
       )}</div>`
     : "";
 
+  // Suppress the "Get started with your AI" card on the no-vault branch:
+  // that branch tells the user "You don't have a vault yet" + "ask the operator
+  // to assign you one," so a do-the-thing card alongside reads as contradictory
+  // (do-this vs you-lack-the-prerequisite). The admin (isFirstAdmin) and
+  // assigned-vault branches both have a vault to act against, so the card
+  // belongs there.
+  const hasNoVault = !isFirstAdmin && assignedVaults.length === 0;
+  const startedCard = hasNoVault ? "" : renderGetStartedCard();
+
   const vaultCard = renderVaultCard({
     assignedVaults,
     trimmedOrigin,
@@ -197,12 +206,51 @@ export function renderAccountHome(opts: RenderAccountHomeOpts): string {
       </div>
       ${mintedBanner}
       ${mintErrorBanner}
+      ${startedCard}
       ${vaultCard}
       ${accountCard}
     </div>${COPY_SCRIPT}`;
   return baseDocument(`${username} — Parachute`, body);
 }
 
+/**
+ * The "Get started with your AI" card — the real first stop for a friend
+ * landing on `/account/`. Mirrors the operator setup-wizard's
+ * `renderStarterPromptsSection` (same two parachute.computer/onboarding/*
+ * links + copy) so friends and operators get the same on-ramp. The prompts
+ * live on parachute.computer rather than embedded here so they iterate
+ * without a hub release; this card just links.
+ *
+ * Placed near the top of the page (after any banners, before the vault card)
+ * because "what do I actually do with this?" is the friend's first question —
+ * the connect details below answer "how", this answers "what next".
+ */
+function renderGetStartedCard(): string {
+  return `
+    <section class="section get-started" data-testid="get-started-card">
+      <h2>Get started with your AI</h2>
+      <p>Two ready-made prompts to paste into Claude (or another AI assistant)
+        once your vault is connected — they walk you through it, no setup
+        knowledge needed.</p>
+      <div class="starter-grid">
+        <a class="starter-tile" href="https://parachute.computer/onboarding/vault-setup/"
+           target="_blank" rel="noopener" data-testid="starter-vault-setup">
+          <h3>Set up your vault</h3>
+          <p>Your AI interviews you about where your notes live now and suggests
+            a structure that fits how you think.</p>
+          <span class="starter-cta">Open prompt ↗</span>
+        </a>
+        <a class="starter-tile" href="https://parachute.computer/onboarding/surface-build/"
+           target="_blank" rel="noopener" data-testid="starter-surface-build">
+          <h3>Build a custom UI</h3>
+          <p>Your AI builds you a little web app for your vault — your own way to
+            see and add to it.</p>
+          <span class="starter-cta">Open prompt ↗</span>
+        </a>
+      </div>
+    </section>`;
+}
+
 interface VaultCardOpts {
   assignedVaults: string[];
   trimmedOrigin: string;
@@ -303,9 +351,9 @@ function renderVaultCard(opts: VaultCardOpts): string {
                  approve. (Your hub must be reachable from the web for this.)</p>
             </div>
 
-            <p class="mcp-connect-hint" data-testid="connect-any-client-hint">Any other MCP
-               client (Codex, Goose, Cursor, your own agent): point it at the same endpoint
-               above over HTTP.</p>
+            <p class="mcp-connect-hint" data-testid="connect-any-client-hint">Using something
+               else? Point any MCP client at the same endpoint above. (ChatGPT and some other
+               web UIs call these "connectors.")</p>
           </div>
           <p class="vault-notes-cta">
             <a class="btn btn-primary" href="https://notes.parachute.computer/add?url=${vaultUrlForAdd}"
@@ -478,19 +526,24 @@ function renderAccountCard(opts: AccountCardOpts): string {
       <dl class="kv">
         <dt>Username</dt>
         <dd><code>${username}</code></dd>
-        <dt>Two-factor authentication</dt>
-        ${twoFactorStatus}
       </dl>
-      <p>
-        <a class="account-action" href="/account/change-password" data-testid="change-password-link">Change password →</a>
-      </p>
-      <p>
-        ${twoFactorLink}
-      </p>
       <form method="POST" action="/logout" class="signout-form" data-testid="signout-form">
         ${renderCsrfHiddenInput(csrfToken)}
         <button type="submit" class="btn btn-secondary">Sign out</button>
       </form>
+      <details class="account-security" data-testid="account-security">
+        <summary>Security &amp; password</summary>
+        <dl class="kv">
+          <dt>Two-factor authentication</dt>
+          ${twoFactorStatus}
+        </dl>
+        <p>
+          <a class="account-action" href="/account/change-password" data-testid="change-password-link">Change password →</a>
+        </p>
+        <p>
+          ${twoFactorLink}
+        </p>
+      </details>
     </section>`;
 }
 
@@ -604,6 +657,60 @@ const STYLES = `
     margin-top: 1.25rem;
   }
   .section p { margin: 0.4rem 0; }
+
+  .get-started h3 {
+    font-family: ${FONT_SERIF};
+    font-weight: 400;
+    font-size: 1rem;
+    margin: 0 0 0.3rem;
+    color: ${PALETTE.fg};
+  }
+  .starter-grid {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 0.75rem;
+    margin: 0.75rem 0 0.2rem;
+  }
+  .starter-tile {
+    display: block;
+    border: 1px solid ${PALETTE.borderLight};
+    border-radius: 8px;
+    padding: 0.8rem 0.9rem;
+    background: ${PALETTE.bgSoft};
+    text-decoration: none;
+    color: inherit;
+    transition: border-color 0.15s ease, background 0.15s ease;
+  }
+  .starter-tile:hover { border-color: ${PALETTE.accent}; background: ${PALETTE.accentSoft}; }
+  .starter-tile p {
+    font-size: 0.84rem;
+    color: ${PALETTE.fgMuted};
+    margin: 0 0 0.5rem;
+  }
+  .starter-cta {
+    font-size: 0.85rem;
+    font-weight: 500;
+    color: ${PALETTE.accent};
+  }
+  @media (max-width: 480px) {
+    .starter-grid { grid-template-columns: 1fr; }
+  }
+
+  .account-security {
+    margin: 0.9rem 0 0;
+    padding-top: 0.6rem;
+    border-top: 1px solid ${PALETTE.borderLight};
+  }
+  .account-security > summary {
+    cursor: pointer;
+    font-size: 0.88rem;
+    font-weight: 600;
+    color: ${PALETTE.fgMuted};
+    list-style: revert;
+  }
+  .account-security > summary:hover { color: ${PALETTE.fg}; }
+  .account-security .kv { margin-top: 0.6rem; }
+
   .vault-name {
     font-family: ${FONT_MONO};
     font-size: 1rem;
@@ -879,7 +986,14 @@ const STYLES = `
     code { background: #1f1c18; color: #e8e4dc; }
     .copy-row code { background: transparent; }
     .section { border-top-color: #3a362f; }
-    .mcp-method, .vault-notes-cta, .token-mint { border-top-color: #3a362f; }
+    .mcp-method, .vault-notes-cta, .token-mint,
+    .account-security { border-top-color: #3a362f; }
+    .get-started h3 { color: #f0ece4; }
+    .starter-tile { border-color: #3a362f; background: #1f1c18; }
+    .starter-tile:hover { border-color: ${PALETTE.accent}; }
+    .starter-tile p { color: #a8a29a; }
+    .account-security > summary { color: #a8a29a; }
+    .account-security > summary:hover { color: #f0ece4; }
     .brand-tag { border-color: #3a362f; color: #a8a29a; }
     .copy-row { background: #1f1c18; border-color: #3a362f; }
     .btn-secondary, .btn-copy { color: #e8e4dc; border-color: #3a362f; }

package/src/cloudflare/connector-service.ts

@@ -69,10 +69,21 @@ export type ConnectorServiceDeps = ManagedUnitDeps;
 
 export const defaultServiceDeps: ConnectorServiceDeps = defaultManagedUnitDeps;
 
+/**
+ * Reverse-DNS prefix for the launchd label + plist filename. Exported so the
+ * migrate/teardown stale-per-module-autostart sweep (`src/stale-module-units.ts`,
+ * hub#522) can reuse it as a SKIP-list anchor — the connector unit is owned by
+ * the supervised model (`expose off --cloudflare` tears it down), and the sweep
+ * must never touch it. Reusing the constant keeps the skip-list from drifting if
+ * this prefix ever changes.
+ */
+export const CLOUDFLARED_LAUNCHD_LABEL_PREFIX = "computer.parachute.cloudflared";
+/** systemd unit name prefix. Exported for the same skip-list reason as above. */
+export const CLOUDFLARED_SYSTEMD_UNIT_PREFIX = "parachute-cloudflared-";
 /** Reverse-DNS prefix for the launchd label + plist filename. */
-const LAUNCHD_LABEL_PREFIX = "computer.parachute.cloudflared";
+const LAUNCHD_LABEL_PREFIX = CLOUDFLARED_LAUNCHD_LABEL_PREFIX;
 /** systemd unit name prefix. */
-const SYSTEMD_UNIT_PREFIX = "parachute-cloudflared-";
+const SYSTEMD_UNIT_PREFIX = CLOUDFLARED_SYSTEMD_UNIT_PREFIX;
 /** Provenance comment baked into every rendered connector unit file. */
 const CONNECTOR_HEADER = "Generated by parachute expose public --cloudflare — do not edit by hand.";
 

package/src/commands/migrate-cutover.ts

@@ -86,6 +86,11 @@ import { type PortListeningFn, defaultPortListening } from "../port-probe.ts";
 import { type AliveFn, clearPid, readPid } from "../process-state.ts";
 import { shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifestLenient } from "../services-manifest.ts";
+import {
+  type DisableStaleModuleUnitsOpts,
+  type DisableStaleModuleUnitsResult,
+  disableStaleModuleUnits,
+} from "../stale-module-units.ts";
 
 /**
  * Absolute path to this hub checkout's `src/cli.ts` — the entry the hub unit's
@@ -180,6 +185,19 @@ export interface CutoverDeps {
   sleep: (ms: number) => Promise<void>;
   /** The hub-unit deps for install / detect / manager calls. */
   hubUnitDeps: HubUnitDeps;
+  /**
+   * Detect + DISABLE any stale per-module autostart unit (#522 — the load-bearing
+   * fix). A leftover standalone `parachute-<short>.service` (systemd KeepAlive) /
+   * `computer.parachute.<short>` (launchd KeepAlive) from the pre-supervisor era
+   * keeps RESPAWNING an unsupervised module that binds the module's port — the
+   * supervised child then EADDRINUSE-crash-loops. Killing the process is
+   * whack-a-mole (the unit resurrects it); we must disable the UNIT. Run in the
+   * STOP phase (after the per-module detached stop, before the port-free verify)
+   * so the freed port lets the supervised module bind. Ownership-safe (known
+   * module shorts only; hub + cloudflared skipped), idempotent, non-fatal.
+   * Injectable so tests never touch real systemctl/launchctl.
+   */
+  disableStaleModuleUnits: (opts?: DisableStaleModuleUnitsOpts) => DisableStaleModuleUnitsResult;
 }
 
 export interface WriteUnitOpts {
@@ -329,6 +347,7 @@ export const defaultCutoverDeps: CutoverDeps = {
   probeHealth: defaultHubUnitDeps.probeHealth,
   sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
   hubUnitDeps: defaultHubUnitDeps,
+  disableStaleModuleUnits,
 };
 
 export interface CutoverOpts {
@@ -673,6 +692,22 @@ export async function cutoverToSupervised(opts: CutoverOpts = {}): Promise<Cutov
     await stopDetachedModule(target, configDir, deps, timeoutMs, pollMs, log);
   }
 
+  // --- Step 3b (#522): DISABLE stale per-module autostart UNITS. ---
+  // The load-bearing fix for the recurring "port 1940 taken" crash-loop: a
+  // leftover standalone `parachute-<short>.service` (systemd KeepAlive) or
+  // `computer.parachute.<short>` (launchd KeepAlive) from the pre-supervisor era
+  // keeps RESPAWNING an unsupervised module that binds the port — so the
+  // per-module stop above (and the orphan sweep below) is whack-a-mole: the unit
+  // resurrects the process within seconds, serving OLD code. We must DISABLE the
+  // UNIT so the port stays free for the supervised child. MUST run HERE — after
+  // the detached stop, BEFORE the verify-ports-free + unit start — so the freed
+  // port lets the supervised module bind. Ownership-safe (known module shorts
+  // only; hub + cloudflared skipped), idempotent, non-fatal (a failed disable
+  // warns + continues; a system-level unit it can't disable → warn with the
+  // manual sudo command). Every disabled unit is reported.
+  log("Checking for stale per-module autostart units to disable…");
+  deps.disableStaleModuleUnits({ deps: deps.hubUnitDeps, log: (l) => log(l) });
+
   // --- Step 4: §7.2 ORPHAN SWEEP — per services.json port + the hub port. ---
   // The HUB port keeps the pre-existing blind-adopt (mirrors stopHub's 1939
   // orphan-adoption — out of scope for MUST-FIX 2). The MODULE ports get the
@@ -797,6 +832,13 @@ export interface TeardownOpts {
     removedLaunchdMessage: (label: string) => string;
     removedSystemdMessage: (unitName: string) => string;
   }) => ManagedUnitRemoveResult;
+  /**
+   * Test seam: the stale-per-module-autostart disable (#522). Teardown also
+   * disables any leftover standalone module autostart unit so a rollback to
+   * foreground `serve` doesn't leave a competing module respawning at boot.
+   * Injectable so tests never touch real systemctl/launchctl.
+   */
+  disableStaleModuleUnits?: (opts?: DisableStaleModuleUnitsOpts) => DisableStaleModuleUnitsResult;
 }
 
 /**
@@ -815,6 +857,7 @@ export function teardownHubUnit(opts: TeardownOpts = {}): { removed: boolean; me
   const log = opts.log ?? ((line) => console.log(line));
   const deps = opts.deps ?? defaultHubUnitDeps;
   const remove = opts.remove ?? removeManagedUnit;
+  const disableStale = opts.disableStaleModuleUnits ?? disableStaleModuleUnits;
   const res = remove({
     launchdLabel: HUB_LAUNCHD_LABEL,
     systemdUnitName: HUB_SYSTEMD_UNIT_NAME,
@@ -824,6 +867,11 @@ export function teardownHubUnit(opts: TeardownOpts = {}): { removed: boolean; me
     removedSystemdMessage: (unitName) =>
       `Removed systemd unit ${unitName} — the hub no longer starts on boot.`,
   });
+  // #522: also disable any leftover standalone per-module autostart unit so a
+  // rollback to foreground `serve` doesn't leave a competing module respawning at
+  // boot to race whatever the operator brings up next. Ownership-safe (known
+  // module shorts only; hub + cloudflared skipped), idempotent, non-fatal.
+  disableStale({ deps, log });
   if (res.removed) {
     for (const m of res.messages) log(m);
     log("");

package/src/managed-unit.ts

@@ -648,10 +648,25 @@ export interface BuildHubManagedUnitOpts {
  *
  * Resolves the absolute `bun` path via the `which` seam (launchd/systemd don't
  * search `$PATH` — mirrors how the connector resolves cloudflared). The env
- * carries `PARACHUTE_HOME` / `PORT` / `PATH` / `BUN_INSTALL` — and INTENTIONALLY
- * OMITS `PARACHUTE_HUB_ORIGIN`: baking a stale origin here would re-create the
- * iss-mismatch class; `resolveStartupIssuer` derives it and start-hub self-heals
- * the operator token + vault `.env` to the current origin (design §4.1 comment).
+ * carries `PARACHUTE_BIND_HOST` / `PARACHUTE_HOME` / `PORT` / `PATH` /
+ * `BUN_INSTALL` — and INTENTIONALLY OMITS `PARACHUTE_HUB_ORIGIN`: baking a stale
+ * origin here would re-create the iss-mismatch class; `resolveStartupIssuer`
+ * derives it and start-hub self-heals the operator token + vault `.env` to the
+ * current origin (design §4.1 comment).
+ *
+ * BIND HOST — `PARACHUTE_BIND_HOST=127.0.0.1` is forced here so every
+ * self-hosted supervised hub binds loopback. `parachute serve` itself defaults
+ * the bind host to `0.0.0.0` (serve.ts), which is correct for the container
+ * shape (the platform's HTTP forwarder must reach the hub) but WRONG for a
+ * self-hosted box — bare `serve` would expose the admin/OAuth surfaces on every
+ * interface, contradicting the pre-supervisor detached behavior and the trust
+ * model `layerOf` (hub-server.ts) assumes (header-absent ⇒ "loopback"). The
+ * container path never calls this builder (the Dockerfile pins
+ * `ENV PARACHUTE_BIND_HOST=0.0.0.0` + runs `serve` directly), so it stays
+ * 0.0.0.0. The canonical expose path is unaffected: cloudflared/tailscale dial
+ * `127.0.0.1:<port>` from the same host, and the hub's own proxy targets
+ * `http://127.0.0.1:<port>` (hub-server.ts). An operator who genuinely wants
+ * all-interfaces can override the generated unit; the default is loopback.
  *
  * NOT called by any command in this PR (additive — Phase 3 wires it into `init`).
  */
@@ -676,6 +691,11 @@ export function buildHubManagedUnit(opts: BuildHubManagedUnitOpts): ManagedUnit
     systemdDescription: "Parachute hub (serve + supervisor)",
     execStart: [bunPath, opts.cliPath, "serve"],
     env: {
+      // Force loopback on every self-hosted supervised hub. serve.ts defaults
+      // to 0.0.0.0 (container-first); a self-hosted box must NOT bare-serve
+      // all-interfaces. Container path bypasses this builder (Dockerfile pins
+      // its own 0.0.0.0). See the docstring for the full trust-model rationale.
+      PARACHUTE_BIND_HOST: "127.0.0.1",
       // PARACHUTE_HOME captured at install time (design §4.2) — NOT the default.
       PARACHUTE_HOME: opts.parachuteHome,
       PORT: String(port),