@scoutmesh/viewer 0.2.0

package/dist/update-manager.js

@@ -0,0 +1,448 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  closeSync,
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { writeStateFile } from "./state-file.js";
+
+const execute = promisify(execFile);
+                        
+              
+               
+              
+               
+                     
+                   
+                  
+ 
+                   
+                  
+                 
+                     
+                    
+ 
+
+function object(value         )                          {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Expected an object.");
+  }
+  return Object.fromEntries(Object.entries(value));
+}
+function readJson(file        ) {
+  return object(
+    JSON.parse(readFileSync(file, "utf-8").replace(/^\uFEFF/u, ""))
+  );
+}
+function version(value         )         {
+  if (typeof value !== "string" || !/^\d+\.\d+\.\d+$/u.test(value)) {
+    throw new Error("Invalid release version.");
+  }
+  return value;
+}
+function installation(root        )               {
+  const input = readJson(path.join(root, "launcher.json"));
+  for (const key of ["cli", "node", "npm", "stateDir"]) {
+    if (typeof input[key] !== "string" || !path.isAbsolute(input[key])) {
+      throw new Error(`Invalid launcher ${key}. Rerun the official bootstrap.`);
+    }
+  }
+  if (
+    typeof input.port !== "number" ||
+    !Number.isInteger(input.port) ||
+    (input.port !== 0 && input.port < 1024) ||
+    input.port > 65_535 ||
+    typeof input.releaseUrl !== "string"
+  ) {
+    throw new Error("Invalid launcher settings.");
+  }
+  return {
+    cli: String(input.cli),
+    node: String(input.node),
+    npm: String(input.npm),
+    port: input.port,
+    releaseUrl: input.releaseUrl,
+    stateDir: String(input.stateDir),
+    version: version(input.version),
+  };
+}
+
+function releaseUrl(value        )      {
+  const url = new URL(value);
+  if (
+    url.username ||
+    url.password ||
+    url.hash ||
+    (url.protocol !== "https:" &&
+      !(url.protocol === "http:" && url.hostname === "127.0.0.1"))
+  ) {
+    throw new Error(
+      "Release URLs must use HTTPS (HTTP loopback is allowed for local tests only)."
+    );
+  }
+  return url;
+}
+async function download(url     , limit        )                  {
+  const response = await fetch(url, {
+    cache: "no-store",
+    redirect: "error",
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!response.ok || !response.body) {
+    throw new Error(`Release download failed: HTTP ${response.status}.`);
+  }
+  const chunks               = [];
+  let size = 0;
+  for await (const chunk of response.body) {
+    size += chunk.length;
+    if (size > limit) {
+      throw new Error("Release download exceeds its size limit.");
+    }
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+async function getRelease(address        )                   {
+  const url = releaseUrl(address);
+  const bytes = await download(url, 64 * 1024);
+  const input = object(JSON.parse(bytes.toString("utf-8")));
+  if (
+    typeof input.sha256 !== "string" ||
+    !/^[a-f0-9]{64}$/u.test(input.sha256) ||
+    typeof input.archiveUrl !== "string" ||
+    input.nodeMajor !== 24
+  ) {
+    throw new Error(
+      "Invalid release manifest or unsupported runtime. Use the current official bootstrap if a newer Node runtime is required."
+    );
+  }
+  const archive = releaseUrl(input.archiveUrl);
+  if (archive.origin !== url.origin) {
+    throw new Error(
+      "The release archive must have the same origin as its manifest."
+    );
+  }
+  return {
+    archiveUrl: archive.href,
+    nodeMajor: input.nodeMajor,
+    sha256: input.sha256,
+    version: version(input.version),
+  };
+}
+function newer(next        , current        ) {
+  const left = next.split(".").map(Number);
+  const right = current.split(".").map(Number);
+  const index = left.findIndex((part, i) => part !== right[i]);
+  return index !== -1 && (left[index] ?? 0) > (right[index] ?? 0);
+}
+function environment(config              ) {
+  const env                    = {
+    ...process.env,
+    SCOUTMESH_VIEWER_HOME: config.stateDir,
+    VIEWER_PORT: String(config.port),
+  };
+  delete env.VIEWER_STATE_FILE;
+  return env;
+}
+async function run(config              , args          ) {
+  return await execute(config.node, [config.cli, ...args], {
+    env: environment(config),
+    timeout: 30_000,
+    windowsHide: true,
+  });
+}
+async function status(config              ) {
+  const result = await run(config, ["status"]);
+  return object(JSON.parse(result.stdout));
+}
+async function startChecked(config              ) {
+  const started = await run(config, ["start"]);
+  const result = await status(config);
+  if (result.status !== "running" || result.version !== config.version) {
+    throw new Error(
+      `Expected running viewer ${config.version}, received ${String(result.version)}.`
+    );
+  }
+  return {
+    ...result,
+    reused: object(JSON.parse(started.stdout)).reused === true,
+  };
+}
+async function stageRelease(
+  root        ,
+  current              ,
+  release         
+)                        {
+  const directory = path.join(
+    root,
+    "packages",
+    `${release.version}-${release.sha256.slice(0, 12)}`
+  );
+  const cli = path.join(
+    directory,
+    "node_modules/@scoutmesh/viewer/dist/cli.js"
+  );
+  const receipt = path.join(directory, ".verified.json");
+  if (
+    existsSync(cli) &&
+    existsSync(receipt) &&
+    readJson(receipt).sha256 === release.sha256
+  ) {
+    return { ...current, cli, version: release.version };
+  }
+  const bytes = await download(
+    releaseUrl(release.archiveUrl),
+    20 * 1024 * 1024
+  );
+  if (createHash("sha256").update(bytes).digest("hex") !== release.sha256) {
+    throw new Error(
+      "Release checksum mismatch. The running viewer was not changed."
+    );
+  }
+  const stage = mkdtempSync(path.join(root, ".update-stage-"));
+  try {
+    const archive = path.join(stage, "viewer.tgz");
+    writeFileSync(archive, bytes, { mode: 0o600 });
+    await execute(
+      current.node,
+      [
+        current.npm,
+        "install",
+        "--offline",
+        "--ignore-scripts",
+        "--no-audit",
+        "--no-fund",
+        "--cache",
+        path.join(root, "npm-cache"),
+        "--prefix",
+        directory,
+        archive,
+      ],
+      { timeout: 60_000, windowsHide: true }
+    );
+    const manifest = readJson(
+      path.join(directory, "node_modules/@scoutmesh/viewer/package.json")
+    );
+    if (
+      manifest.name !== "@scoutmesh/viewer" ||
+      manifest.version !== release.version
+    ) {
+      throw new Error("Release package identity does not match its manifest.");
+    }
+    writeStateFile(receipt, {
+      sha256: release.sha256,
+      version: release.version,
+    });
+    return { ...current, cli, version: release.version };
+  } catch (error) {
+    rmSync(directory, { force: true, recursive: true });
+    throw error;
+  } finally {
+    rmSync(stage, { force: true, recursive: true });
+  }
+}
+
+async function switchRelease(
+  root        ,
+  current              ,
+  next              
+) {
+  const state = path.join(current.stateDir, "state.json");
+  const backup = path.join(
+    current.stateDir,
+    "backups",
+    `upgrade-${Date.now()}-${randomUUID()}`
+  );
+  mkdirSync(backup, { mode: 0o700, recursive: true });
+  // Stop the writer before capturing a consistent snapshot, including last-second UI decisions.
+  await run(current, ["stop"]);
+  const hadState = existsSync(state);
+  try {
+    if (hadState) {
+      copyFileSync(state, path.join(backup, "before.json"));
+    }
+    writeStateFile(path.join(backup, "installation.json"), current);
+  } catch (error) {
+    await startChecked(current);
+    throw new Error(
+      "Could not create an upgrade backup. The previous viewer was restarted; no update was applied.",
+      { cause: error }
+    );
+  }
+  try {
+    const running = await startChecked(next);
+    writeStateFile(path.join(root, "launcher.json"), next);
+    return { ...running, backup, update: "updated" };
+  } catch (error) {
+    // Never restore a snapshot over a live or unreachable server.
+    try {
+      await run(next, ["stop"]);
+    } catch {
+      throw new Error(
+        `Upgrade could not be stopped safely. State was not restored. Recovery files: ${backup}.`,
+        { cause: error }
+      );
+    }
+    if (existsSync(state)) {
+      copyFileSync(state, path.join(backup, "failed.json"));
+    }
+    if (hadState) {
+      writeStateFile(
+        state,
+        JSON.parse(readFileSync(path.join(backup, "before.json"), "utf-8"))
+      );
+    } else {
+      rmSync(state, { force: true });
+    }
+    writeStateFile(path.join(root, "launcher.json"), current);
+    const running = await startChecked(current);
+    console.error(
+      `Update failed; restored viewer ${current.version}. ${error instanceof Error ? error.message : "Startup failed."}`
+    );
+    return { ...running, backup, update: "rolled-back" };
+  }
+}
+
+async function updateAndStart(root        , current              ) {
+  if (!current.releaseUrl) {
+    return { ...(await startChecked(current)), update: "not-configured" };
+  }
+  let release         ;
+  let next              ;
+  try {
+    release = await getRelease(current.releaseUrl);
+    if (!newer(release.version, current.version)) {
+      return {
+        ...(await startChecked(current)),
+        update:
+          release.version === current.version ? "current" : "newer-installed",
+      };
+    }
+    next = await stageRelease(root, current, release);
+  } catch (error) {
+    console.error(
+      `Update not applied: ${error instanceof Error ? error.message : "Release check failed."} Using installed viewer ${current.version}.`
+    );
+    return { ...(await startChecked(current)), update: "unavailable" };
+  }
+  return await switchRelease(root, current, next);
+}
+
+async function withLock   (root        , action                  )             {
+  const lockFile = path.join(root, ".update.lock");
+  let lock        ;
+  try {
+    lock = openSync(lockFile, "wx", 0o600);
+  } catch {
+    throw new Error(
+      `Another launcher command owns ${lockFile}. Retry after it finishes. If interrupted, confirm no updater is running before removing this lock.`
+    );
+  }
+  try {
+    writeFileSync(lock, String(process.pid));
+    return await action();
+  } finally {
+    closeSync(lock);
+    rmSync(lockFile, { force: true });
+  }
+}
+
+export async function managedCommand(root        , args          ) {
+  await withLock(root, async () => {
+    const config = installation(root);
+    if (args[0] === "start") {
+      console.info(JSON.stringify(await updateAndStart(root, config)));
+    } else {
+      const result = await run(config, args);
+      process.stdout.write(result.stdout);
+      process.stderr.write(result.stderr);
+    }
+  });
+}
+
+// npm selects and verifies the requested package. Keep a durable copy so clearing
+// the npm cache cannot remove a running viewer or its rollback version.
+export async function launchPackage(packageDir        , stateDir        ) {
+  const manifest = readJson(path.join(packageDir, "package.json"));
+  if (manifest.name !== "@scoutmesh/viewer") {
+    throw new Error("Unexpected npm package identity.");
+  }
+  const requested = version(manifest.version);
+  const root = path.join(stateDir, ".viewer");
+  mkdirSync(root, { mode: 0o700, recursive: true });
+  return await withLock(root, async () => {
+    const configFile = path.join(root, "launcher.json");
+    const current = existsSync(configFile) ? installation(root) : undefined;
+    const launcher = path.join(root, "launcher.mjs");
+    if (current && !newer(requested, current.version)) {
+      return {
+        ...(await startChecked(current)),
+        launcher,
+        node: current.node,
+        update: requested === current.version ? "current" : "newer-installed",
+      };
+    }
+    const packages = path.join(root, "packages");
+    mkdirSync(packages, { mode: 0o700, recursive: true });
+    const staged = mkdtempSync(path.join(packages, ".stage-"));
+    const destination = path.join(packages, `${requested}-${randomUUID()}`);
+    try {
+      for (const name of ["package.json", "dist", "skills", "README.md"]) {
+        cpSync(path.join(packageDir, name), path.join(staged, name), {
+          recursive: true,
+        });
+      }
+      renameSync(staged, destination);
+    } finally {
+      rmSync(staged, { force: true, recursive: true });
+    }
+    const next               = {
+      cli: path.join(destination, "dist/cli.js"),
+      node: process.execPath,
+      // No registry calls are made by this launcher. npm resolves the package
+      // before launch; keep this path for the shared installation format.
+      npm: path.resolve(
+        process.env.npm_execpath ??
+          path.join(
+            path.dirname(process.execPath),
+            process.platform === "win32"
+              ? "node_modules/npm/bin/npm-cli.js"
+              : "../lib/node_modules/npm/bin/npm-cli.js"
+          )
+      ),
+      port: current?.port ?? Number(process.env.VIEWER_PORT ?? 0),
+      releaseUrl: "",
+      stateDir,
+      version: requested,
+    };
+    if (
+      !Number.isInteger(next.port) ||
+      (next.port !== 0 && next.port < 1024) ||
+      next.port > 65_535
+    ) {
+      throw new Error("VIEWER_PORT must be 0 or between 1024 and 65535.");
+    }
+    // The existing launcher remains compatible; do not replace it during an
+    // upgrade that may roll back.
+    if (!current) {
+      copyFileSync(path.join(destination, "dist/launcher.js"), launcher);
+      const running = await startChecked(next);
+      writeStateFile(configFile, next);
+      return { ...running, launcher, node: next.node, update: "installed" };
+    }
+    const result = await switchRelease(root, current, next);
+    return { ...result, launcher, node: installation(root).node };
+  });
+}

package/dist/version.js

@@ -0,0 +1 @@
+export const viewerVersion = "0.2.0";

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@scoutmesh/viewer",
+  "version": "0.2.0",
+  "description": "Local candidate cards and JSON workspaces for ScoutMesh agents",
+  "bin": {
+    "scoutmesh-viewer": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "README.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/skills/local-candidate-viewer/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: local-candidate-viewer
+description: Present ScoutMesh candidates as local interactive cards, append batches, and read shortlist decisions. Requires an agent with terminal access and a browser on the user's computer.
+---
+
+# Local candidate workspace
+
+Use the viewer when the user wants to review candidates visually or continue an
+existing candidate workspace. Keep ScoutMesh searches and billing in the existing
+connector. The viewer only receives already retrieved data; it does not search,
+enrich, verify contacts, or send messages. Candidate data is saved locally as JSON.
+
+## Start and open
+
+The agent needs a terminal and a browser that can reach the same computer's
+localhost. A cloud-only chat cannot start or reach this viewer through the remote
+ScoutMesh connector. Explain that limitation if local execution is unavailable;
+use the usual chat presentation without claiming a page was opened.
+
+This is an unpublished preview. Until ScoutMesh confirms a published version,
+use the supplied local build or verified bootstrap; do not assume the package is
+available. Once confirmed, prefer npm when Node.js 24+ and npm are available:
+
+```bash
+npx --yes --ignore-scripts --registry=https://registry.npmjs.org @scoutmesh/viewer@<approved-version> launch
+```
+
+Substitute the exact version supplied by ScoutMesh, never an invented version.
+Run this command at each new review session so the approved version can replace
+an older running version. `launch` keeps durable package copies outside npm's
+cache and uses state backup, health checks, and rollback during upgrades. It
+returns `node` and `launcher` absolute paths. For subsequent commands below,
+`scoutmesh-viewer` means `"<node>" "<launcher>"`; on Windows use
+`& '<node>' '<launcher>'`. It is not assumed to be on PATH. Keep using this
+launcher for the session, including token and request commands.
+The saved launcher's `start` can restart offline but does not check npm. `current`
+compares the installed version with the requested version; it does not establish
+that a cached version is the newest public release. If npm cannot download the
+approved version, the existing launcher may be used with that limitation stated.
+
+If Node/npm is absent, use the bootstrap ZIP URL and SHA-256 supplied by ScoutMesh.
+Download to a file, verify the checksum, then extract it. Do not invent a release
+URL or pipe downloads into a shell. Run `/bin/bash /absolute/path/to/bootstrap.sh`
+on macOS or `powershell.exe -NoProfile -File C:\absolute\path\bootstrap.ps1` on
+Windows. It downloads a pinned official Node runtime if needed, checks its
+checksum, and installs the bundled viewer offline with lifecycle scripts disabled.
+Use the returned bootstrap launcher for every command in that session. It checks
+its configured release channel on `start`; an unpublished bundle may have none.
+
+Preserve the installation method and state directory for an existing workspace.
+Do not alternate between npm and bootstrap launchers against the same state file.
+Changing delivery methods requires stopping the existing viewer first and
+explicitly preserving its state directory. npm defaults to
+`~/.scoutmesh/workspaces` on both platforms; `SCOUTMESH_VIEWER_HOME` selects another
+directory. npm `launch` rejects `VIEWER_STATE_FILE`. The bootstrap defaults to
+`~/.scoutmesh/workspaces` on macOS and `%LOCALAPPDATA%\ScoutMesh\workspaces` on
+Windows. Do not change locations merely because a command fails.
+
+The host may require approval for downloads, local processes, localhost access,
+or PowerShell scripts. Use its normal approval mechanism. If localhost is blocked,
+retry the documented CLI with approved local access. Do not bypass a rejection by
+reading runtime credentials manually, changing execution policy, or disabling auth.
+Report that limitation if access is unavailable; do not claim the page was opened.
+
+1. Start the session with the versioned npm `launch` command above, or the existing
+   bootstrap launcher’s `start`. It returns JSON with `url`, `stateFile`, and
+   whether it reused a running process, its `version`, and `update` result.
+   `installed` means the first npm installation;
+   `current` means the requested npm version or configured channel matches; `updated` means a verified upgrade;
+   `newer-installed` means no downgrade was attempted. `unavailable` uses the
+   installed version because the release check/install failed. `rolled-back`
+   means an upgrade failed and the previous package/state were restored.
+   `not-configured` means this launcher has no HTTPS release channel; npm updates
+   are selected by the session’s versioned npm command. Report
+   unavailable/rolled-back/not-configured honestly; never call them up to date.
+   This starts a background process, not a
+   login service. Start a new session after a laptop restart.
+2. Run `scoutmesh-viewer request GET /api/views`. Reuse the workspace for this
+   role/search. Create a new one only for a distinct user task. Read its records
+   and decisions before another search so removed or already reviewed people
+   are not presented as new; local deduplication cannot prevent provider charges.
+3. Write the create/update payload to a local JSON file using a file tool, then
+   pass the path to `request`. Do not interpolate candidate text into shell code.
+   Keep temporary candidate files private and remove them when finished.
+4. Open the returned workspace URL in the agent's browser. If it shows Unlock,
+   read `scoutmesh-viewer token` locally and fill the Local access token field,
+   then click Unlock workspace. Never paste the token in chat, a URL, a search,
+   or a remote tool. The browser gets an HttpOnly session cookie. A server
+   restart rotates the token; reload and unlock the page again if needed.
+5. Confirm cards are visible before saying they were shown. An API response
+   confirms a saved mutation, not successful browser rendering.
+
+The bootstrap saves `state.json` under `~/.scoutmesh/workspaces` on macOS and
+`%LOCALAPPDATA%\ScoutMesh\workspaces` on Windows. This is outside the installation.
+The direct npm CLI also accepts `SCOUTMESH_VIEWER_HOME` or `VIEWER_STATE_FILE`.
+`VIEWER_PORT=0` chooses an available port, which can change on restart: always use
+the returned URL. `status` and `stop` affect only the authenticated viewer for this
+state file. The managed launcher stops/restarts safely for an update. Stop before
+manually replacing package files or restoring JSON. Use the returned URL after an
+upgrade and unlock again; the port and local session may change.
+
+A release channel is embedded in official bootstrap bundles. If ScoutMesh supplies
+one separately, pass `--release-url` on macOS or `-ReleaseUrl` on Windows when
+running the installer. Never invent a release URL or silently switch the source.
+The updater preserves snapshots in the state directory and refuses to restore
+over a live/unreachable process. An interrupted upgrade can need manual recovery;
+keep both snapshots and report the diagnostic paths rather than clearing state.
+
+## Send candidates
+
+Create with `scoutmesh-viewer request POST /api/views <create.json>`:
+
+```json
+{
+  "id": "engineering-amsterdam",
+  "title": "Engineering managers · Amsterdam",
+  "records": [
+    {
+      "id": "provider:stable-id",
+      "name": "Example candidate",
+      "role": "Engineering manager",
+      "company": "Example company",
+      "location": "Amsterdam",
+      "fitSummary": "Their profile reports leading a platform team.",
+      "unconfirmed": "Team size and current availability are not confirmed.",
+      "batchId": "batch-1"
+    }
+  ]
+}
+```
+
+This is illustrative data; send the actual search results, never these examples
+as real people. Use stable provider IDs; reuse the existing ID for cross-source
+enrichment only after confirming the identity. Never match by name alone.
+Candidate fields accept strings, finite numbers, booleans, null, and string arrays.
+Flatten nested provider data into useful fields without losing source qualifiers.
+
+Cards use `name`, `role`, `company`, `location`, `photoUrl`, `fitSummary`, and
+`unconfirmed`. Details use `justification`, `gaps`, skills and other supplied
+fields. Include `linkedin`, `github`, `website`, `email`, `emailStatus`,
+`photoSource`, and `photoSourceUrl` only when supported by the returned data.
+Photos must come from the candidate's source; do not invent or generate them.
+Keep a concise role-specific reason and the important unknowns visible in each
+card. A title or repository is evidence of an activity, not proof of proficiency.
+Preserve named source links, dates, and contact verification provenance. Do not
+mark an email independently verified based solely on a provider's claim.
+
+For another batch or enrichment, use
+`scoutmesh-viewer request PATCH /api/views/engineering-amsterdam <update.json>`:
+
+```json
+{
+  "updateId": "batch-2",
+  "expectedRevision": 1,
+  "operation": "upsert",
+  "records": [
+    {
+      "id": "provider:next-id",
+      "name": "Another candidate",
+      "batchId": "batch-2"
+    }
+  ]
+}
+```
+
+Read the current view for its revision. Upsert appends new IDs and merges fields
+for existing IDs while preserving decisions. Keep the same `updateId` AND body
+when retrying an uncertain request. Reusing it with different data returns 409.
+For a revision conflict, reread and reassess before issuing a new update. Never
+replace the workspace to add a batch. The viewer shows 20 cards per page and a
+View new notice for new IDs. Enrichment should not produce a new candidate.
+
+## Work with the shortlist
+
+Read `GET /api/views/<id>/state` immediately before acting on a shortlist.
+The UI uses Yes, Maybe, and No. `selectedIds` is Yes (the current shortlist);
+`maybeIds` is Maybe; `removedIds` is No (set-aside people). The default Unreviewed tab contains
+people in none of those lists. All includes every candidate, including removed ones.
+Read `GET /api/views/<id>` for their records. Do not infer selections from earlier
+chat messages. If the user explicitly requests a decision change, PUT the full
+state to `/api/views/<id>/state`, preserving unrelated IDs and the legacy
+`filter`, `sortBy`, and `sortDirection` fields. A candidate can be in only one of the three decision lists. Move them by updating
+all three arrays in the same request, preserving unrelated decisions. Existing files
+without `maybeIds` load with an empty list; omitting `maybeIds` or `removedIds`
+in an older request preserves that array's current value.
+This single-user preview uses last-write-wins decisions; reread before changes.
+
+When asked to draft outreach, upsert `draftSubject` and `draftEmail` on the
+shortlisted records. These appear in profile details and persist across restarts.
+Profiles separate Overview, Career, and Contact, hiding empty sections. Drafts
+appear in Contact. Keep `fitSummary` and `unconfirmed` concise; longer reasoning
+goes in `justification` and `gaps` behind Read full assessment.
+Drafting is not permission to send, reveal paid contacts, or verify emails.
+Use the existing ScoutMesh outreach and cost guidance for those separate steps.
+
+Limits: 20 workspaces, 2,000 records per workspace, 2 MB per request. Split large
+batches into separate updates with distinct IDs. Live browser updates use SSE;
+missed events are recovered by fetching the latest view on reconnect. Pagination
+limits rendered cards; the API still returns a full workspace. Browser page
+position, open profiles, Undo, and View new notices reset on reload.