@tokenoftrust/cli 1.3.4-rc.3 → 1.3.4-rc.5

package/src/commands/dev.mjs

@@ -42,6 +42,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient, CLI_VERSION, setRunnerVersion, versionStamp } from "../mcp.mjs";
 import { establishSession } from "../auth.mjs";
 import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
+import { emitObstacle } from "../obstacle.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
@@ -51,6 +52,7 @@ import {
 } from "../sample.mjs";
 import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
+import { cockpitUrlFrom } from "../banner.mjs";
 
 /** The published runner image (--docker fallback). Override with --image / TOT_DEV_IMAGE. */
 const DEFAULT_DEV_IMAGE =
@@ -251,7 +253,7 @@ function runMonorepo(ctx, argv) {
     // still tears the runner down — the child stays in our process group and
     // owns the TTY signal.
     const child = spawn(process.execPath, [script, ...argv], { stdio: ["ignore", "pipe", "pipe"], env });
-    streamDevLogs(child);
+    streamDevLogs(child, { cockpitUrl: cockpitUrlFrom(env.TOT_DEV_ACTIVITY_URL) });
     child.on("exit", (code) => resolvePromise(code ?? 0));
     child.on("error", (e) => {
       console.error(`✗ could not start the dev runner: ${e.message}`);
@@ -322,7 +324,7 @@ export function bootNative(runnerDir, workspace, port, url, args) {
   // dropped, real errors pass through. Ctrl-C still tears the server down — the
   // child stays in our process group and owns the TTY signals.
   const handle = spawnNativeDev(runnerDir, workspace, port, { stdio: "piped", env: bridgeEnv });
-  streamDevLogs(handle.child);
+  streamDevLogs(handle.child, { cockpitUrl: cockpitUrlFrom(bridgeEnv.TOT_DEV_ACTIVITY_URL) });
 
   // Heartbeat the hosted cockpit (G1) with the CLI version + this live localhost
   // URL while the runner runs — CLI-side, using the SAME bridge credential the
@@ -928,7 +930,7 @@ export async function installRunnerTarball({ source, version, isUrl = true, stri
       stages: [{ afterMs: 20000, text: "still setting up the preview engine (first run only)…" }],
     });
     try {
-      runPnpmInstall(stagingDir, { logPath: installLog });
+      await runPnpmInstall(stagingDir, { logPath: installLog });
     } finally {
       installSpin.stop();
     }
@@ -982,12 +984,15 @@ function extractTarball(archivePath, destDir, { strip = 0 } = {}) {
 
 /**
  * Activate the exact package manager the runner's package.json pins
- * (packageManager: "pnpm@x.y.z"), via corepack — Node 20+ ships corepack, so
- * this needs no separate pnpm install on the host. Best-effort: if corepack
- * itself is missing (very old Node), pnpm install below will surface that
- * clearly instead.
+ * (packageManager: "pnpm@x.y.z"), via corepack — Node 22.12+ (the CLI's floor)
+ * always bundles corepack, so this PINS a real pnpm without any global `npm i -g
+ * pnpm` (which floats whatever's latest). Best-effort: if corepack itself is
+ * missing or disabled (a locked-down host), pnpm install below falls through to
+ * the pnpm-missing obstacle instead of failing here.
+ * @param {string} runnerDir
+ * @param {{ logPath?: string, spawnFn?: typeof spawnSync }} [opts]
  */
-function ensureCorepackPnpm(runnerDir, { logPath } = {}) {
+export function ensureCorepackPnpm(runnerDir, { logPath, spawnFn = spawnSync } = {}) {
   const pkgPath = join(runnerDir, "package.json");
   if (!existsSync(pkgPath)) return;
   let pm;
@@ -1005,7 +1010,7 @@ function ensureCorepackPnpm(runnerDir, { logPath } = {}) {
     // WITHOUT the global shim (see runPnpmInstall's fallback). Capture both to the
     // log — a silent corepack failure was why the install error carried no cause.
     for (const args of [["enable"], ["prepare", pm, "--activate"]]) {
-      const r = spawnSync("corepack", args, { stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"] });
+      const r = spawnFn("corepack", args, { stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"] });
       if (fd !== null && (r.error || r.status !== 0)) {
         writeSync(fd, `[tot] corepack ${args.join(" ")} → ${r.error?.code || r.error?.message || `exit ${r.status}`}\n`);
       }
@@ -1021,8 +1026,37 @@ function ensureCorepackPnpm(runnerDir, { logPath } = {}) {
  * churn) is captured to a log file instead of flooding the terminal, so the
  * caller's spinner owns the screen. On failure we surface a clean, business-
  * readable message + the log path — never the raw node/pnpm firehose.
+ * @param {string} runnerDir
+ * @param {{ logPath?: string, spawnFn?: typeof spawnSync }} [opts]
  */
-function runPnpmInstall(runnerDir, { logPath } = {}) {
+/**
+ * Run a child process to completion WITHOUT blocking the event loop, resolving
+ * the SAME `{ status, error }` shape spawnSync returns so runPnpmInstall's
+ * launcher-fallback logic reads it unchanged. This non-blocking spawn is what
+ * lets the "installing the store preview engine…" spinner keep ticking during
+ * the long npm install (spawnSync would freeze it at "(0s)"). An ENOENT (launcher
+ * not on PATH) surfaces via the async 'error' event as `{ status: null, error }`,
+ * matching what spawnSync produced for the same case.
+ * @param {string} cmd @param {string[]} args @param {object} opts
+ * @returns {Promise<{ status: number|null, error: Error|null, signal?: string|null }>}
+ */
+function spawnAsyncResult(cmd, args, opts = {}) {
+  return new Promise((resolvePromise) => {
+    let settled = false;
+    const settle = (v) => { if (!settled) { settled = true; resolvePromise(v); } };
+    let child;
+    try {
+      child = spawn(cmd, args, opts);
+    } catch (error) {
+      settle({ status: null, error });
+      return;
+    }
+    child.on("error", (error) => settle({ status: null, error }));
+    child.on("close", (status, signal) => settle({ status, error: null, signal }));
+  });
+}
+
+export async function runPnpmInstall(runnerDir, { logPath, spawnFn = spawnAsyncResult } = {}) {
   const fd = logPath ? openSync(logPath, "a") : null;
   const installArgs = ["install", "--config.dangerouslyAllowAllBuilds=true"];
   // npm FIRST: it ships with EVERY Node (including 25+, where corepack is no
@@ -1043,7 +1077,13 @@ function runPnpmInstall(runnerDir, { logPath } = {}) {
   ];
   try {
     for (const { cmd, args } of attempts) {
-      const r = spawnSync(cmd, args, {
+      // Awaited: the default spawnFn (spawnAsyncResult) runs the launcher
+      // NON-BLOCKING so the caller's "installing…" spinner keeps ticking during
+      // the (long, one-time) npm install instead of freezing at "(0s)" — a
+      // synchronous spawnSync would hold the event loop and starve the interval.
+      // Tests inject a synchronous stub returning { status, error }; awaiting a
+      // plain (non-thenable) value is a no-op, so that contract is unchanged.
+      const r = await spawnFn(cmd, args, {
         cwd: runnerDir,
         // Send both streams to the log fd (or swallow them) — never inherit.
         stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"],
@@ -1055,6 +1095,7 @@ function runPnpmInstall(runnerDir, { logPath } = {}) {
         continue;
       }
       // The launcher ran; the install itself failed. That's the actionable error.
+      await emitObstacle("install-failed");
       throw new CliError(
         `couldn't set up the store preview engine${pnpmFailureHint(logPath)}` +
           (logPath ? `\n     details: ${logPath}` : ""),
@@ -1064,6 +1105,7 @@ function runPnpmInstall(runnerDir, { logPath } = {}) {
     // Every launcher ENOENT'd → there's no pnpm on this machine and corepack
     // couldn't provide one (corepack isn't bundled on Node 25+). npm ships with
     // every Node, so `npm i -g pnpm` is the escape hatch that always exists.
+    await emitObstacle("pnpm-missing");
     throw new CliError(
       "couldn't set up the store preview engine — pnpm isn't available on this machine" +
         (logPath ? `\n     details: ${logPath}` : ""),
@@ -1107,11 +1149,16 @@ export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit",
   // doesn't understand the bare string "piped", so map it to the array here.
   const stdioArr = stdio === "piped" ? ["ignore", "pipe", "pipe"] : stdio;
   // `env` (e.g. activityBridgeEnv()) merges OVER process.env — {} is a pure
-  // passthrough, identical to the old no-env-key behavior.
+  // passthrough, identical to the old no-env-key behavior. Append `--no-warnings`
+  // to NODE_OPTIONS so the runner's Node process never emits the scary
+  // `(node:NNNN) ExperimentalWarning: …` boot noise to the developer (b4);
+  // appended (not replaced) so any host-set NODE_OPTIONS is preserved.
+  const mergedEnv = { ...process.env, ...env };
+  mergedEnv.NODE_OPTIONS = `${mergedEnv.NODE_OPTIONS ? `${mergedEnv.NODE_OPTIONS} ` : ""}--no-warnings`;
   const child = spawn(
     process.execPath,
     [script, "--workspace", workspace, "--port", port],
-    { cwd: runnerDir, stdio: stdioArr, env: { ...process.env, ...env } },
+    { cwd: runnerDir, stdio: stdioArr, env: mergedEnv },
   );
   const handle = { child, exited: false, done: null };
   handle.done = new Promise((resolvePromise) => {
@@ -1145,7 +1192,7 @@ async function runContainer(workspace, args, ctx) {
   // piping is safe; Ctrl-C still stops the container (docker stays in our
   // process group and forwards the signal, with `--init` reaping it inside).
   const handle = await spawnDevContainer(plan, args, { stdio: "piped" });
-  streamDevLogs(handle.child);
+  streamDevLogs(handle.child, { cockpitUrl: cockpitUrlFrom(activityBridgeEnv().TOT_DEV_ACTIVITY_URL) });
 
   // Heartbeat the hosted cockpit (G1) CLI-side while the container runs — the
   // container reports file-saves via the threaded env, but the CLI owns the

package/src/commands/start.mjs

@@ -67,6 +67,7 @@ import {
 import { scaffoldSample, isSampleCheckout, sampleConfig, SAMPLE_DIR_NAME } from "../sample.mjs";
 import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
+import { milestoneBanner, cockpitUrlFrom, DEVELOPER_COCKPIT } from "../banner.mjs";
 import { IDEAS } from "./ideas.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -196,15 +197,36 @@ export async function run(argv, ctx) {
     await preflight(ctx, env);
     console.log(`  ✓ signed in as ${describeIdentity(session)} via ${mcpOrigin(baseUrl)}`);
 
+    // Resolve the activity-bridge credential + the hosted Developer Cockpit URL
+    // ONCE, up front — both the pre-pick "keep the cockpit alive" heartbeat below
+    // (b2) and the post-boot heartbeat + milestone banners (u2) use them.
+    const bridgeEnv = activityBridgeEnv(env);
+    const cockpitUrl = cockpitUrlFrom(bridgeEnv.TOT_DEV_ACTIVITY_URL);
+
+    // b2 — a >1-store identity blocks on the interactive store picker below, and
+    // (before this) the hosted cockpit got NO heartbeat until the dev server
+    // spawned much later, so a multi-store dev's cockpit sat on Step 1 forever
+    // while the terminal quietly waited for a number. Start beating NOW (no local
+    // URL yet — the store isn't checked out) so the cockpit keeps receiving
+    // liveness during the pick + checkout + boot; the post-boot heartbeat (with
+    // the live localhost URL) takes over once we have it.
+    const stopEarlyHeartbeat = startHeartbeatFromEnv(bridgeEnv, {});
+
     // 3. store — auto-pick, use --tenant, use the remembered one, or choose (A4).
     // Keep the raw client_list so a tool ERROR (unauthenticated / not-entitled) is
     // surfaced with who + where, not collapsed to an empty list (fb-...f45zg9).
-    const listResp = await client.callTool("client_list", {});
-    const stores = normalizeStores(listResp);
-    const tenant = await resolveTenant(stores, args, env, baseUrl, {
-      session,
-      listErr: storeListError(listResp),
-    });
+    let tenant;
+    try {
+      const listResp = await client.callTool("client_list", {});
+      const stores = normalizeStores(listResp);
+      tenant = await resolveTenant(stores, args, env, baseUrl, {
+        session,
+        listErr: storeListError(listResp),
+      });
+    } catch (e) {
+      stopEarlyHeartbeat();
+      throw e;
+    }
 
     // 4. checkout → ./<tenant> (reuse an existing checkout on a re-run),
     // OVERLAPPED (C1) with prefetching the runner: the native artifact by
@@ -225,11 +247,15 @@ export async function run(argv, ctx) {
       prefetchRuntime(client, devArgs, env, runtime, ctx),
     ]);
 
+    // u3 — say EXACTLY where the code landed + THE one next step, so a freshly
+    // checked-out dev is never left wondering what to open. Absolute path (works
+    // from any directory) and a single, unambiguous action.
+    printCheckoutLanding(dir, cockpitUrl);
+
     // 5. dev — native by default (F3), Docker on --docker or the fallback
     // above; wait for the server, open the browser (C/D).
     const ctxDev = detectContext(dir);
     let url, handle;
-    const bridgeEnv = activityBridgeEnv(env);
     if (runtime.useDocker) {
       const plan = buildContainerPlan(dir, devArgs, ctxDev);
       url = plan.url;
@@ -244,7 +270,10 @@ export async function run(argv, ctx) {
     // Heartbeat the hosted cockpit (G1) with the CLI version + this live localhost
     // URL for the life of the run — CLI-side, using the cached bridge credential
     // (no-op when none is cached). The runner keeps reporting file-saves itself.
-    const stopHeartbeat = startHeartbeatFromEnv(bridgeEnv, { url });
+    // Hand off from the pre-pick (URL-less) beat to this URL-bearing one so the
+    // cockpit's live local link lights up exactly when the server is up (b2).
+    stopEarlyHeartbeat();
+    const stopHeartbeat = startHeartbeatFromEnv(bridgeEnv, { url, cwd: dir });
     handle.done.finally(() => stopHeartbeat());
 
     // The runner's stdio is "piped" (its logs are held until the aha), so this
@@ -264,11 +293,11 @@ export async function run(argv, ctx) {
     // (A3) so the "instant" claim is measured. The "Connect Claude" step is
     // intentionally removed for now — a blocking prompt here meant Ctrl-C'ing it
     // tore down the dev server; revisit AI-connect as a non-blocking step later.
-    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt));
+    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt), cockpitUrl);
 
     // 7. hand the terminal to the running dev server until Ctrl-C.
     console.log("\n  Watching your store — edit content/home.html + save. Ctrl-C to stop.\n");
-    streamDevLogs(handle.child);
+    streamDevLogs(handle.child, { cockpitUrl });
     return handle.done;
   } catch (e) {
     console.error(formatError(e));
@@ -547,8 +576,14 @@ async function resolveTenant(stores, args, env, baseUrl, { session = null, listE
         next: `tot start --tenant <tenant>  (one of: ${pick.stores.map((s) => s.id).join(", ")})`,
       });
     }
-    console.log("  Which store do you want to work on?\n");
+    // Loud + unmissable: a >1-store dev is often looking at their browser
+    // cockpit (which is waiting on this pick), so make the terminal shout for
+    // their attention rather than sitting as a quiet one-liner (b2).
+    console.log("");
+    console.log("  ⚑ ACTION NEEDED IN YOUR TERMINAL — you can build on several stores.");
+    console.log("    Pick one here to light up your cockpit:\n");
     pick.stores.forEach((s, i) => console.log(`    ${i + 1}. ${s.id}${s.name ? `  — ${s.name}` : ""}`));
+    console.log("");
     const idx = await promptChoice(pick.stores.length);
     console.log("");
     tenant = pick.stores[idx].id;
@@ -611,13 +646,37 @@ export function formatElapsed(ms) {
   return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
 }
 
-/** The crafted "you're live" ending — leads with the AI-wow (G), seeded with
- * IDEAS[0] (G2/G3 — one prompt list shared with `tot ideas`, no drift). */
-function printLiveEnding(tenant, url, elapsed) {
+/**
+ * u3 — after checkout, tell the developer EXACTLY where their code landed and
+ * THE single next step. `dir` is absolute (from resolve(cwd, tenant)) so the
+ * "open this" path works no matter what directory they're in. When we know the
+ * Developer Cockpit URL, the one next step is framed as "edit a line → see it in
+ * your cockpit"; otherwise it's the same edit-to-see-it-reload action.
+ */
+function printCheckoutLanding(dir, cockpitUrl = null) {
   console.log("");
-  console.log(`  ✨ You're live.${elapsed ? `  (${elapsed})` : ""}`);
-  console.log(`     ${url}`);
-  console.log("     Edit content/home.html + save → it reloads.");
+  console.log(`  📁 Your store code is at:  ${dir}`);
+  const where = cockpitUrl ? `your ${DEVELOPER_COCKPIT}` : "your browser";
+  console.log(`     Next: open it in your editor and change one line in`);
+  console.log(`     content/home.html — you'll see it reflected in ${where}.`);
+}
+
+/** The crafted "you're live" ending — a PROMINENT milestone banner (u2) that,
+ * when we hold a Developer Cockpit URL, explicitly sends the developer BACK to
+ * their cockpit as the next place to look; then the AI-wow (G), seeded with
+ * IDEAS[0] (G2/G3 — one prompt list shared with `tot ideas`, no drift). */
+function printLiveEnding(tenant, url, elapsed, cockpitUrl = null) {
+  const lines = [
+    `✨  You're live.${elapsed ? `  (${elapsed})` : ""}`,
+    `    ${url}`,
+    "    Edit content/home.html + save → it reloads.",
+  ];
+  if (cockpitUrl) {
+    lines.push("");
+    lines.push(`➜  Back to your ${DEVELOPER_COCKPIT} to watch it happen:`);
+    lines.push(`   ${cockpitUrl}`);
+  }
+  console.log(milestoneBanner(lines));
   console.log("  " + versionStamp("native"));
   console.log("");
   console.log("  Now try, in Claude:");

package/src/commands/validate.mjs

@@ -79,6 +79,10 @@ export function run(argv, ctx) {
   const { ok, findings } = validateTenant(target.dir, {
     tenantId: target.tenantId ?? undefined,
     scope: target.scope ?? undefined,
+    // A checkout / bare-tenant target is served by the ToT storefront platform, so
+    // commerce tenants own the framework routes (/collections, /account, …). Only an
+    // arbitrary --workspace <dir> stays conservative (unless its config resolves the host).
+    mode: args.workspace ? "workspace" : "monorepo",
   });
 
   if (args.json) {

package/src/dev-logs.mjs

@@ -4,9 +4,10 @@
  * (dev.mjs). Extracted so the two entrypoints stream identically instead of one
  * inheriting the raw vite/astro firehose while the other collapses it.
  *
- * Dependency-free (no imports) — pure line buffering + filtering over a child's
- * stdout/stderr.
+ * Depends only on the shared, dependency-free banner helper — otherwise pure
+ * line buffering + filtering over a child's stdout/stderr.
  */
+import { milestoneBanner, DEVELOPER_COCKPIT } from "./banner.mjs";
 
 /**
  * Stream the running dev server's output in BUSINESS terms. The runner + Vite +
@@ -16,17 +17,32 @@
  * save-reload into one clean "↻ your store reloaded", drop the known internal
  * noise, and pass anything else through (indented) so nothing important is
  * hidden. Ctrl-C still tears the server down (the child owns the TTY signals).
+ *
+ * The FIRST save→reload is the aha milestone (u2): with a `cockpitUrl` it's a
+ * PROMINENT banner that sends the developer back to their Developer Cockpit to
+ * see the change; every reload after that is the quiet "↻ your store reloaded"
+ * line so a working dev loop doesn't get spammed with banners.
  * @param {import("node:child_process").ChildProcess} child
+ * @param {{ cockpitUrl?: string|null, out?: (s: string) => void, reloadDebounceMs?: number }} [opts]
+ *   `out` is the sink (default: process.stdout.write) — injectable for tests.
+ *   `reloadDebounceMs` collapses a single save's HMR burst into one line (default 1000ms).
  */
-export function streamDevLogs(child) {
+export function streamDevLogs(
+  child,
+  { cockpitUrl = null, out = (s) => process.stdout.write(s), reloadDebounceMs = 1000 } = {},
+) {
   // Startup churn + tool internals — never user-facing. Matched AFTER stripping
   // the runner/Vite "HH:MM:SS " timestamp prefix (see `body` below), so a
   // timestamped internal line like "10:50:17 [vite] connected" is still dropped.
+  // The node:* / ExperimentalWarning / (node:NNNN) / "--trace-warnings" and the
+  // boot "fatal: not a git repository" lines are dropped too (b4) — scary,
+  // non-actionable boot noise that reads as a broken first run.
   const NOISE =
-    /^(\[vite\]|\[types\]|\[@astrojs|\[WARN\]|▲|┃|astro\s+v[\d.]|(Local|Network)\s+http|watching for file changes|Scope: all \d|copy-tenant-assets:|.*dependency optimized|.*optimized dependencies changed|.*program reload|\d+ deprecated|Packages:\s*\+|Progress:\s*resolved|Downloading @|node_modules\/|devDependencies:|\+\s+\w+@|Done in \d)/i;
+    /^(\[vite\]|\[types\]|\[@astrojs|\[WARN\]|▲|┃|astro\s+v[\d.]|(Local|Network)\s+http|watching for file changes|Scope: all \d|copy-tenant-assets:|.*dependency optimized|.*optimized dependencies changed|.*program reload|\d+ deprecated|Packages:\s*\+|Progress:\s*resolved|Downloading @|node_modules\/|devDependencies:|\+\s+\w+@|Done in \d|\(node:\d+\)|ExperimentalWarning|node:internal\/|\(Use `node --trace-warnings|fatal: not a git repository)/i;
   // A real save-triggered reload (not startup "program reload" churn).
   const RELOAD = /(hmr update|page reload)/i;
   let reloadPending = null;
+  let sawFirstReload = false;
   const emit = (line) => {
     const t = line.replace(/\s+$/, "");
     if (!t) return;
@@ -35,13 +51,24 @@ export function streamDevLogs(child) {
     const body = t.replace(/^\d{1,2}:\d{2}:\d{2}(\.\d+)?\s+/, "").replace(/^\s+/, "");
     if (RELOAD.test(body)) {
       if (reloadPending) return; // debounce a burst into one line
-      reloadPending = setTimeout(() => { reloadPending = null; }, 1000);
+      reloadPending = setTimeout(() => { reloadPending = null; }, reloadDebounceMs);
       if (reloadPending.unref) reloadPending.unref();
-      process.stdout.write("  ↻ your store reloaded\n");
+      if (!sawFirstReload && cockpitUrl) {
+        sawFirstReload = true;
+        out(milestoneBanner([
+          "↻  Your edit is live — your store reloaded.",
+          "",
+          `➜  See it in your ${DEVELOPER_COCKPIT}:`,
+          `   ${cockpitUrl}`,
+        ]) + "\n");
+        return;
+      }
+      sawFirstReload = true;
+      out("  ↻ your store reloaded\n");
       return;
     }
     if (NOISE.test(body)) return;
-    process.stdout.write(`  ${t}\n`);
+    out(`  ${t}\n`);
   };
   lineStream(child.stdout, emit);
   lineStream(child.stderr, emit);

package/src/obstacle-beacon.cjs

@@ -0,0 +1,111 @@
+/**
+ * The obstacle beacon — a fire-and-forget POST that tells the hosted cockpit a
+ * `tot start` / `tot checkout` failed, so it can show the exact fix in the bridge
+ * strip (obstacle lane, server side already shipped). Best-effort telemetry that
+ * rides ALONGSIDE the house-style `✗ … → next:` error; it must NEVER change,
+ * delay past its timeout, or fail that error path.
+ *
+ *   KEEP THIS FILE ES5/CommonJS: var, string concat, function expressions — no
+ *   arrow functions, template literals, optional chaining, or const/let. The ES5
+ *   launcher (bin/tot.cjs) require()s this on a machine that FAILED the Node
+ *   floor (Node < 22.12, no global `fetch`, no ESM) to beacon `node-too-old`
+ *   pre-login — the exact old-Node dead-end the whole obstacle lane exists for.
+ *   So this uses require("https"/"http"), and a test keeps it parseable by
+ *   ancient Nodes. The ESM side (src/obstacle.mjs) imports beaconAsync from here
+ *   too, so the wire shape + endpoint live in ONE place and can't drift.
+ *
+ * The event contract is DECIDED (owned by the server's rail-obstacle-lane):
+ *   POST <activity-url>/api/dev/activity   Authorization: Bearer <token>
+ *   { event:"obstacle", kind, have?, need?, cliVersion?, at? }
+ * Send ONLY these machine-readable fields — the human remediation copy is composed
+ * SERVER-side per kind, so guidance changes without a CLI release. The server
+ * stamps its own reportedAt (skew-proof) and a later heartbeat CLEARS the obstacle.
+ */
+"use strict";
+
+var VALID_KINDS = { "node-too-old": 1, "pnpm-missing": 1, "install-failed": 1, "clone-failed": 1 };
+var TIMEOUT_MS = 2000;
+
+/**
+ * Pull --activity-url / --activity-token straight out of argv. The launcher runs
+ * BEFORE any arg framework (and before login has cached anything), so on the
+ * node-too-old path this is the only source of the bridge credential — the pasted
+ * setup command carries both flags. Returns {} for whatever is absent.
+ */
+function parseActivityArgs(argv) {
+  var out = { url: undefined, token: undefined };
+  if (!argv) return out;
+  for (var i = 0; i < argv.length; i++) {
+    if (argv[i] === "--activity-url") out.url = argv[i + 1];
+    else if (argv[i] === "--activity-token") out.token = argv[i + 1];
+  }
+  return out;
+}
+
+/**
+ * Fire one obstacle beacon. Everything is wrapped so it can never throw into the
+ * caller's error path; `done` is invoked EXACTLY once (on success, error, timeout,
+ * or a skip) — the launcher passes process.exit as `done` so the process lingers
+ * only as long as the beacon (≤ TIMEOUT_MS) before exiting.
+ *   opts: { url, token, kind, have?, need?, cliVersion?, at? }
+ */
+function beacon(opts, done) {
+  var finished = false;
+  function finish() {
+    if (finished) return;
+    finished = true;
+    try { if (timer) clearTimeout(timer); } catch (e) {}
+    if (typeof done === "function") { try { done(); } catch (e) {} }
+  }
+  var timer = null;
+  try {
+    opts = opts || {};
+    if (!opts.url || !opts.token || !VALID_KINDS[opts.kind]) { finish(); return; }
+
+    var body = { event: "obstacle", kind: opts.kind };
+    if (opts.have) body.have = opts.have;
+    if (opts.need) body.need = opts.need;
+    if (opts.cliVersion) body.cliVersion = opts.cliVersion;
+    body.at = opts.at || Date.now();
+    var payload = JSON.stringify(body);
+
+    var endpoint = String(opts.url).replace(/\/+$/, "") + "/api/dev/activity";
+    var lib = endpoint.indexOf("http://") === 0 ? require("http") : require("https");
+
+    // A hard timeout guarantees the caller's exit (or await) is bounded even if
+    // the socket hangs — telemetry never holds a failing developer hostage.
+    timer = setTimeout(finish, TIMEOUT_MS);
+
+    var req = lib.request(
+      endpoint,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: "Bearer " + opts.token,
+          "content-length": Buffer.byteLength(payload),
+        },
+      },
+      function (res) {
+        // Drain and finish — we don't care about the status, only that it was sent.
+        res.on("data", function () {});
+        res.on("end", finish);
+        res.on("error", finish);
+      }
+    );
+    req.on("error", finish);
+    req.write(payload);
+    req.end();
+  } catch (e) {
+    finish();
+  }
+}
+
+/** Promise wrapper for the ESM side (src/obstacle.mjs) so a failure path can await delivery. */
+function beaconAsync(opts) {
+  return new Promise(function (resolve) {
+    try { beacon(opts, resolve); } catch (e) { resolve(); }
+  });
+}
+
+module.exports = { parseActivityArgs: parseActivityArgs, beacon: beacon, beaconAsync: beaconAsync };

package/src/obstacle.mjs

@@ -0,0 +1,35 @@
+/**
+ * ESM front door to the obstacle beacon (src/obstacle-beacon.cjs). The post-login
+ * failure paths — `pnpm-missing`, `install-failed`, `clone-failed` — run on a
+ * supported Node where the bridge credential is already cached, so they resolve
+ * {url, token} from ~/.tot/credentials.json (the same source activityBridgeEnv +
+ * the heartbeat use) rather than argv. `node-too-old` does NOT come through here:
+ * it fires from the ES5 launcher pre-login, where creds may not exist yet.
+ *
+ * emitObstacle is awaited at the failure site so the packet is delivered before
+ * the process prints its `✗ … → next:` and exits — but it is fully swallowed, so
+ * telemetry can never disrupt or delay (past the beacon's own ~2s timeout) the
+ * error the developer actually needs to see.
+ */
+import beaconCore from "./obstacle-beacon.cjs";
+import { CLI_VERSION } from "./mcp.mjs";
+import { defaultCredentialsPath, readCredentials } from "./token-store.mjs";
+
+/**
+ * Best-effort obstacle beacon for a post-login failure. No-op (silent) when no
+ * bridge credential is cached — the developer signed in with a build that didn't
+ * carry the activity flags, or ran a bare `tot login`.
+ * @param {"pnpm-missing"|"install-failed"|"clone-failed"} kind
+ * @param {{ have?: string, need?: string, env?: NodeJS.ProcessEnv }} [opts]
+ */
+export async function emitObstacle(kind, { have, need, env = process.env } = {}) {
+  try {
+    const creds = readCredentials(defaultCredentialsPath(env));
+    const url = creds?.activityUrl;
+    const token = creds?.activityToken;
+    if (!url || !token) return;
+    await beaconCore.beaconAsync({ url, token, kind, have, need, cliVersion: CLI_VERSION });
+  } catch {
+    /* best-effort telemetry — never disrupts the error path */
+  }
+}