milestone(boot-timing): instrument the boot path — measure before we refactor — Fixes #80

Step 0 of Refactoring-for-API-Speed: the shell wasn't timing itself, so "it's
slow" had no shape. Adds a dependency-free bootMark/bootSummary timer to
@augment-it/workspace and stamps every boot milestone:

  shell:mount → ws:connect-start → ws:open → ws:session-verified
  → workspace.list:sent/returned → workspace.activate:sent/returned
  → workspaces:ready (+ a console.table summary)

Each mark logs per-step and cumulative ms. On by default; silence with
localStorage 'augment_boot_timing'='off'. Marks live at the real seams —
transport.ts (connect/open/session frame) and state.svelte.ts loadWorkspaces —
so the numbers are the actual wall-clock, not a guess.

Verified: packages/workspace tsc + the transport property test (4) green; shell
rsbuild build green. The timeline prints to the browser console on next load
(after redeploy, or in local dev) — that's the measurement that decides whether
the 60s is the readiness race (a day's fix) or a deeper refactor.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018UYTYu4MAFZ7iyr2VTo2kq

Author: mpstaton

packages/workspace/src/boot-timing.ts

@@ -0,0 +1,60 @@
+// boot-timing.ts — dead-simple boot-path instrumentation. No library.
+//
+// Step 0 of context-v/issues/Refactoring-for-API-Speed.md: the wall-clock the
+// operator feels lives in the browser, and the shell wasn't timing itself.
+// bootMark() stamps a milestone with performance.now() and logs elapsed ms, so
+// "it's slow" becomes "workspace.activate took 58s and everything else 300ms".
+//
+// One timeline per page load (module singleton). Each federation container has
+// its own copy — the shell's timeline is the boot the user waits on. On by
+// default; silence with localStorage.setItem('augment_boot_timing','off').
+
+type Mark = { name: string; at: number };
+
+function now(): number {
+  return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+
+let t0: number | null = null;
+let last = 0;
+const marks: Mark[] = [];
+
+function enabled(): boolean {
+  try {
+    return typeof localStorage === 'undefined' || localStorage.getItem('augment_boot_timing') !== 'off';
+  } catch {
+    return true;
+  }
+}
+
+/** Stamp a boot milestone. The first mark anchors T0 for the whole timeline. */
+export function bootMark(name: string): void {
+  if (!enabled()) return;
+  const at = now();
+  if (t0 === null) {
+    t0 = at;
+    last = at;
+  }
+  const sincePrev = at - last;
+  const sinceStart = at - t0;
+  last = at;
+  marks.push({ name, at });
+  console.info(
+    `%c[boot]%c ${name.padEnd(26)} +${String(Math.round(sincePrev)).padStart(6)}ms   (T+${Math.round(sinceStart)}ms)`,
+    'color:#8b5cf6;font-weight:bold',
+    'color:inherit',
+  );
+}
+
+/** Print the whole timeline as a table. Call at the final milestone. */
+export function bootSummary(label = 'boot complete'): void {
+  if (!enabled() || t0 === null) return;
+  bootMark(label);
+  const base = t0;
+  const rows = marks.map((m, i) => ({
+    milestone: m.name,
+    'Δprev (ms)': i === 0 ? 0 : Math.round(m.at - marks[i - 1].at),
+    'T+ (ms)': Math.round(m.at - base),
+  }));
+  console.table?.(rows);
+}

packages/workspace/src/index.ts

@@ -1,4 +1,5 @@
 export { workspace, WORKSPACE_CHANGED_EVENT } from './state.svelte';
+export { bootMark, bootSummary } from './boot-timing';
 export { createAdapter } from './adapter';
 export { createTransport } from './transport';
 export { suggest } from './anticipation';

packages/workspace/src/state.svelte.ts

@@ -15,6 +15,7 @@
 // rule in https://svelte.dev/e/state_invalid_placement.
 
 import { createTransport, type ChatTurnReply, type ChatTurnRequest, type Transport, type TransportConfig } from './transport';
+import { bootMark, bootSummary } from './boot-timing';
 import type { ActiveView, JobEvent, PromptTemplate, RecordSet, Row, ServerFrame, UserContext, WorkspaceSummary } from './types';
 
 // Where the browser stashes the operator's active workspace pick. Survives
@@ -178,11 +179,13 @@ class AugmentItWorkspace {
     this.workspaces_error = null;
     try {
       console.info('[workspace] loadWorkspaces → workspace.list');
+      bootMark('workspace.list:sent');
       const result = (await this.invoke('workspace.list', {})) as {
         workspaces: WorkspaceSummary[];
         active_client_id: string | null;
         pinned?: boolean;
       };
+      bootMark('workspace.list:returned');
       console.info('[workspace] workspace.list returned', result);
       this.workspaces = result.workspaces;
       this.pinned = result.pinned ?? false;
@@ -198,12 +201,15 @@ class AugmentItWorkspace {
       // split-brain (browser shows one tenant, domain services scope to
       // another) until the operator manually re-picks in the switcher.
       if (resolved && resolved !== result.active_client_id) {
+        bootMark('workspace.activate:sent');
         await this.invoke('workspace.activate', { client_id: resolved });
+        bootMark('workspace.activate:returned');
       }
       if (resolved !== persisted) {
         this.setActiveClientId(resolved);
       }
       this.workspaces_status = 'ready';
+      bootSummary('workspaces:ready');
       return resolved;
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);

packages/workspace/src/transport.ts

@@ -26,6 +26,7 @@ import type {
   ResultFrame,
   ServerFrame,
 } from './types';
+import { bootMark } from './boot-timing';
 
 export type TransportConfig = {
   url: string;                              // e.g. 'ws://localhost:3001/ws'
@@ -121,6 +122,7 @@ export function createTransport(config: TransportConfig): Transport {
       ? `${config.url}?token=${encodeURIComponent(token)}`
       : config.url;
 
+    bootMark('ws:connect-start');
     config.onStatus?.('connecting');
     ws = new WebSocket(url);
 
@@ -158,6 +160,7 @@ export function createTransport(config: TransportConfig): Transport {
       backoff = reconnectInitialMs;
       authDead = false;
       authRefreshTried = false;
+      bootMark('ws:open');
       config.onStatus?.('open');
       // Frames still in the queue were never delivered — flush re-sends
       // them as ordinary invokes. Pending entries NOT in the queue were
@@ -185,6 +188,7 @@ export function createTransport(config: TransportConfig): Transport {
       }
 
       if (frame.kind === 'session') {
+        bootMark('ws:session-verified');
         config.saveToken(frame.token);
       } else if (frame.kind === 'result') {
         const p = pending.get(frame.id);

shell/src/App.svelte

@@ -8,7 +8,7 @@
   import SignInWall from './SignInWall.svelte';
   import JumboPopdown, { type PopdownItem } from './JumboPopdown.svelte';
   import ToggleHeader from '@augment-it/shared-ui/ToggleHeader__PromptOrPackage--Icons.svelte';
-  import { workspace } from '@augment-it/workspace';
+  import { workspace, bootMark } from '@augment-it/workspace';
   import {
     PAIRINGS,
     CHAT_REMOTE,
@@ -357,6 +357,7 @@
   // on the singleton, so if a remote raced us and connected first the
   // second call is a no-op.
   onMount(() => {
+    bootMark('shell:mount'); // T0 for the boot timeline — see Refactoring-for-API-Speed
     const TOKEN_KEY = 'augment_it_session_token';
     // Fire BEFORE/alongside connect(), not after — an anonymous WS upgrade
     // against a DIDI_AUTH=required instance is rejected (4401) before any