@dadado/agent-kit-cli 4.8.8 → 5.0.0

package/dashboard/lib/semantic-model.mjs

@@ -24,10 +24,16 @@ export const MONITOR_FEED_CAP = 20;
 /** Cap agent_step rows emitted per active plan for the denser Crew feed. */
 export const MONITOR_AGENT_STEP_EMIT_CAP = 12;
 
+/** Cap subagent-run rows emitted per snapshot (fs scan bounds live in dashboard-data.mjs). */
+export const MONITOR_SUBAGENT_EMIT_CAP = 8;
+/** Cap plan_review pointer rows emitted per snapshot. */
+export const MONITOR_PLAN_REVIEW_EMIT_CAP = 4;
+
 /**
  * Monitor hero curated subset over the semantic activity stream.
  * Live agent steps: run_plan / handoff / delivery plus agent_step (Task/orchestrator
- * to-do steps). plan_progress milestones stay on Activity / Checklist.
+ * to-do steps), subagent (Task worker lifecycle) and plan_review (background
+ * mid-batch review pointers). plan_progress milestones stay on Activity / Checklist.
  * Activity (Phase 2) is the superset; inventory kinds are excluded here.
  */
 export const MONITOR_ACTIVITY_KINDS = Object.freeze([
@@ -35,6 +41,8 @@ export const MONITOR_ACTIVITY_KINDS = Object.freeze([
   "handoff",
   "delivery",
   "agent_step",
+  "subagent",
+  "plan_review",
 ]);
 
 /**
@@ -2152,9 +2160,12 @@ export function formatDeliveryActivity(logLines, { plans = [], limit = MAX_GIT_A
     const kitAgent = normalizeKitAgentId(agent);
     const actor = briefActivityActor(kitAgent, { kind: "delivery", plan: planName });
     const prBit = `PR #${entry.pr}`;
+    // Verb `merged` (not `shipped`, retired 2026-08-05): the row is derived from
+    // a merge/squash entry, and `shipped` implied a prod promote /git-staging
+    // never performed.
     const label = brief
-      ? `${actor} \u00b7 shipped \u00b7 ${brief} \u00b7 ${prBit} \u00b7 ${entry.sha}`
-      : `${actor} \u00b7 shipped \u00b7 ${prBit} \u00b7 ${entry.sha}`;
+      ? `${actor} \u00b7 merged \u00b7 ${brief} \u00b7 ${prBit} \u00b7 ${entry.sha}`
+      : `${actor} \u00b7 merged \u00b7 ${prBit} \u00b7 ${entry.sha}`;
     const commitType = parseDeliveryCommitType(brief, { hasPr: entry.pr != null });
     events.push({
       id: activityId("delivery", ["merge", String(entry.pr)]),
@@ -2173,18 +2184,23 @@ export function formatDeliveryActivity(logLines, { plans = [], limit = MAX_GIT_A
 
 /**
  * Actor segment for Monitor return-brief labels.
- * Kit agent id, else Engineering Manager for delivery, else Squad when a plan
- * is present (never the full plan filename), else Platform Engineer.
- * Default software lexicon display masks (resolution kinds unchanged).
+ * Kit agent id, else `Eng` for delivery, else `SQ` when a plan is present
+ * (never the full plan filename), else `Eng`.
+ *
+ * Short display masks from the operator lexicon (2026-08-05): Engineering
+ * Manager -> Eng, Squad -> SQ, Platform Engineer -> Eng. `Eng` is a documented
+ * collision between the delivery and system fallbacks; the resolution keys
+ * (`orchestrator` / `crew` / `system`) and the row's kind glyph stay distinct.
+ * ADR: decisions/2026-07-27_crew-monitor-vs-plan-monitor-glossary.md.
  * @param {string|null|undefined} agent
  * @param {{ kind?: string, plan?: string|null }} [opts]
  */
 export function briefActivityActor(agent, { kind, plan } = {}) {
   const kit = normalizeKitAgentId(agent);
   if (kit) return kit;
-  if (kind === "delivery") return "Engineering Manager";
-  if (plan) return "Squad";
-  return "Platform Engineer";
+  if (kind === "delivery") return "Eng";
+  if (plan) return "SQ";
+  return "Eng";
 }
 
 /**
@@ -2316,6 +2332,191 @@ export function formatPlanHandoffActivity({ now, handoff, plans }) {
   return events;
 }
 
+/**
+ * Task subagent transcripts are `<uuid>.jsonl` inside a parent chat's
+ * `subagents/` directory.
+ */
+export const SUBAGENT_TRANSCRIPT_FILE_RE = /^([0-9a-fA-F][0-9a-fA-F-]{7,})\.jsonl$/;
+
+/**
+ * Worker-prompt fields the kit's own dispatch template declares (see
+ * `.cursor/commands/run-plan.md`). Both forms occur in real dispatches: the
+ * bare `To-do id: x` of the plain template and the `- **worker_type:** x` of a
+ * bulleted orchestrator prompt, so the leading list marker and the markdown
+ * emphasis on either side of the colon are optional. The captured value
+ * excludes `*` and a backtick so `**explore**` and `` `explore` `` yield
+ * `explore` rather than the decoration.
+ */
+const SUBAGENT_TODO_ID_RE =
+  /^[ \t]*(?:[-*][ \t]*)?\**To-?do id\**[ \t]*[:=][ \t]*\**[ \t]*([^\s*`]+)/im;
+const SUBAGENT_WORKER_TYPE_RE =
+  /^[ \t]*(?:[-*][ \t]*)?\**(?:worker_type(?:[ \t]*\/[ \t]*subagent_type)?|subagent_type)\**[ \t]*[:=][ \t]*\**[ \t]*([^\s*`]+)/im;
+
+/** Plain-text content of a transcript entry (user prompt or assistant reply). */
+function subagentEntryText(entry) {
+  const content = entry?.message?.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const c of content) {
+    if (c && c.type === "text" && typeof c.text === "string") parts.push(c.text);
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Lifecycle of one Task subagent run, from the two records that carry it: the
+ * dispatch prompt (first entry) and the terminal record (last entry).
+ *
+ * Phase contract: a transcript whose last record is not `turn_ended` is still
+ * `running`; `turn_ended` with `status: "success"` is `done`; any other status
+ * (including `error`) is `failed`. A transcript that is empty or entirely
+ * unparsable yields `null` rather than a phantom running row.
+ *
+ * The fs half (directory layout, recency window, file/byte caps) lives in
+ * `dashboard-data.mjs` next to the agent-prompt scan contract. Transcript paths
+ * live under `$HOME`, never in the repo, so no `sourcePath` is emitted.
+ *
+ * @param {{ id?: string, parentId?: string|null, firstLine?: string, lastLine?: string, modifiedAt?: string|null }} input
+ * @returns {{ id: string, parentId: string|null, phase: 'running'|'done'|'failed', todoId: string|null, workerType: string|null, modifiedAt: string|null }|null}
+ */
+export function parseSubagentRun({
+  id,
+  parentId = null,
+  firstLine = "",
+  lastLine = "",
+  modifiedAt = null,
+} = {}) {
+  const runId = String(id || "").trim();
+  if (!runId) return null;
+
+  let first = null;
+  let last = null;
+  try {
+    first = firstLine ? JSON.parse(firstLine) : null;
+  } catch {
+    first = null;
+  }
+  try {
+    last = lastLine ? JSON.parse(lastLine) : null;
+  } catch {
+    last = null;
+  }
+  if (!first && !last) return null;
+
+  let phase = "running";
+  if (last && last.type === "turn_ended") {
+    phase = last.status === "success" ? "done" : "failed";
+  }
+
+  const promptText = first && first.role === "user" ? subagentEntryText(first) : "";
+  const todoMatch = promptText ? SUBAGENT_TODO_ID_RE.exec(promptText) : null;
+  const typeMatch = promptText ? SUBAGENT_WORKER_TYPE_RE.exec(promptText) : null;
+  const rawTodo = todoMatch ? todoMatch[1] : null;
+  const rawType = typeMatch ? typeMatch[1] : null;
+  // The template writes literal placeholders when a field is unset; those are
+  // not identities and must not reach a row.
+  const placeholder = /^(?:<.*>|none|n\/a|-{1,2})$/i;
+  return {
+    id: runId,
+    parentId: parentId ? String(parentId) : null,
+    phase,
+    todoId: rawTodo && !placeholder.test(rawTodo) ? rawTodo : null,
+    workerType: rawType && !placeholder.test(rawType) ? rawType : null,
+    modifiedAt: modifiedAt || null,
+  };
+}
+
+/**
+ * Live Crew Monitor rows for Task subagent runs (start / still running /
+ * complete / failed). Newest first; the caller passes an already-bounded list.
+ *
+ * Deliberately a distinct kind from `agent_step`: `agent_step` is derived from
+ * plan to-do status, so a subagent that runs without flipping a to-do would be
+ * invisible there and a to-do flipped by hand would be misattributed to a
+ * worker. ADR: decisions/2026-07-27_crew-monitor-vs-plan-monitor-glossary.md.
+ *
+ * @param {object[]} runs - `parseSubagentRun` output
+ * @param {{ limit?: number }} [opts]
+ */
+export function formatSubagentActivity(runs, { limit = MONITOR_SUBAGENT_EMIT_CAP } = {}) {
+  const events = [];
+  for (const run of runs || []) {
+    if (events.length >= limit) break;
+    if (!run || !run.id) continue;
+    const kitAgent = normalizeKitAgentId(run.workerType);
+    // Display actor is the dispatched worker type whenever the prompt declared
+    // one: a built-in type such as `explore` is a real worker identity even
+    // though it is not a `.cursor/agents/` id. `agent` stays kit-id-only so
+    // downstream attribution is unchanged. `Dev` is the operator-lexicon mask
+    // for Developer / Full-Stack Developer, used when no type was declared.
+    const actor = run.workerType ? truncateStr(String(run.workerType), 24) : "Dev";
+    const shortId = String(run.id).slice(0, 8);
+    const subject = run.todoId || "task";
+    const visible = `${actor} · ${run.phase} · ${subject} · ${shortId}`;
+    events.push({
+      id: activityId("subagent", [run.id, run.phase]),
+      kind: "subagent",
+      at: run.modifiedAt || null,
+      agent: kitAgent,
+      label: truncateStr(visible, MAX_SEMANTIC_LABEL),
+      labelFull: visible,
+      // Transcripts live outside the repo (under $HOME); no repo path to copy.
+      sourcePath: null,
+      refs: { subagent: run.id, parent: run.parentId || null, phase: run.phase, todo: run.todoId },
+    });
+  }
+  return events;
+}
+
+/**
+ * Crew Monitor pointer rows for background mid-batch plan reviews.
+ *
+ * The operator cannot otherwise see that a review ran: `plan-monitor-*.md` lands
+ * silently in `.cursor/memory/` and only surfaces once Flight Log / attention
+ * picks it up. These rows say a review exists and whether it is still owed
+ * triage. They are pointers only — Flight Log and the attention inbox keep sole
+ * ownership of triage state and actions, and a row never marks anything
+ * reviewed. Boundary amend recorded in the glossary ADR (2026-08-05).
+ *
+ * @param {object[]} reports - `parseExternalReport` output
+ * @param {object[]} plans - plan records from the snapshot
+ * @param {{ limit?: number }} [opts]
+ */
+export function formatPlanReviewActivity(
+  reports,
+  plans,
+  { limit = MONITOR_PLAN_REVIEW_EMIT_CAP } = {},
+) {
+  const sorted = (reports || [])
+    .filter((r) => r?.file)
+    .slice()
+    .sort((a, b) => String(b.modifiedAt || "").localeCompare(String(a.modifiedAt || "")));
+
+  const events = [];
+  for (const report of sorted) {
+    if (events.length >= limit) break;
+    const triaged = isReportTriaged(report, plans);
+    // `awaiting` reuses the existing gate verb: the review itself has landed,
+    // what is outstanding is the operator's triage.
+    const verb = triaged ? "done" : "awaiting";
+    // `QA` is the operator-lexicon mask for QA Engineer.
+    const planRef = report.reviewedPlanFile || `${report.slug}.plan.md`;
+    const visible = `QA · ${verb} · review · ${planRef}`;
+    events.push({
+      id: activityId("plan_review", [report.file, triaged ? "triaged" : "open"]),
+      kind: "plan_review",
+      at: report.modifiedAt || null,
+      agent: null,
+      label: truncateStr(visible, MAX_SEMANTIC_LABEL),
+      labelFull: visible,
+      sourcePath: report.path || null,
+      refs: { plan: report.reviewedPlanFile || null, report: report.file, triaged },
+    });
+  }
+  return events;
+}
+
 /**
  * Explicit run-plan loop lines in terminal output. Shared detection for the
  * Crew feed (formatTerminalRunEvidence) and the busy-outside-plan derivation
@@ -3562,6 +3763,7 @@ export function buildMissionControlView({
   deferredCheckIds = [],
   agentPrompts = [],
   externalReports = [],
+  subagentRuns = [],
   dismissedIds = [],
   archivedPlanFiles = [],
   agents = [],
@@ -3615,7 +3817,11 @@ export function buildMissionControlView({
   const activity = mergeActivity([
     planEvents.filter((e) => e.kind === "run_plan" || e.kind === "handoff"),
     planEvents.filter((e) => e.kind === "agent_step"),
+    // Live Task-worker lifecycle before delivery: a running subagent is the
+    // freshest thing on the board and must not be starved by MAX_ACTIVITY.
+    formatSubagentActivity(subagentRuns),
     deliveryEvents,
+    formatPlanReviewActivity(externalReports, plans),
     planEvents.filter((e) => e.kind === "plan_progress"),
     formatGitActivity(gitLogLines, { excludeShas: supersededShas }),
     formatTerminalRunEvidence(terminals),

package/dashboard/open.html

@@ -0,0 +1,213 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex,nofollow" />
+    <title>Mission Control share</title>
+    <style>
+      :root {
+        color-scheme: dark light;
+        --bg: #0f1419;
+        --fg: #e7ecf1;
+        --muted: #8b9aab;
+        --accent: #3b82f6;
+        --err: #f87171;
+        --card: #1a222c;
+      }
+      @media (prefers-color-scheme: light) {
+        :root {
+          --bg: #f4f6f8;
+          --fg: #12202e;
+          --muted: #5b6b7c;
+          --card: #ffffff;
+        }
+      }
+      * {
+        box-sizing: border-box;
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif;
+        background: var(--bg);
+        color: var(--fg);
+        display: grid;
+        place-items: center;
+        padding: 1.5rem;
+      }
+      main {
+        width: min(28rem, 100%);
+        background: var(--card);
+        border-radius: 12px;
+        padding: 1.5rem 1.35rem;
+        box-shadow: 0 12px 40px rgb(0 0 0 / 18%);
+      }
+      h1 {
+        font-size: 1.15rem;
+        margin: 0 0 0.5rem;
+        font-weight: 650;
+      }
+      p {
+        margin: 0 0 1rem;
+        color: var(--muted);
+        font-size: 0.95rem;
+        line-height: 1.45;
+      }
+      .err {
+        color: var(--err);
+      }
+      a.btn,
+      button.btn {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 100%;
+        border: 0;
+        border-radius: 8px;
+        padding: 0.75rem 1rem;
+        font: inherit;
+        font-weight: 600;
+        text-decoration: none;
+        cursor: pointer;
+        background: var(--accent);
+        color: #fff;
+      }
+      a.btn[hidden],
+      button.btn[hidden] {
+        display: none;
+      }
+      .note {
+        margin-top: 1rem;
+        font-size: 0.8rem;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Mission Control</h1>
+      <p id="status">Opening your local Mission Control…</p>
+      <a id="open" class="btn" hidden href="#">Open Mission Control</a>
+      <p class="note">
+        Cosmetic share link only. You must be on the same trusted LAN (or VPN) as the host.
+        Treat the full Share URL as a secret (it embeds the session token in the fragment).
+        Only private/loopback LAN targets are accepted.
+      </p>
+    </main>
+    <script>
+      (function () {
+        var statusEl = document.getElementById("status");
+        var openEl = document.getElementById("open");
+
+        function fail(msg) {
+          statusEl.textContent = msg;
+          statusEl.className = "err";
+          openEl.hidden = true;
+        }
+
+        function isPrivateOrLoopbackHostname(hostname) {
+          var host = String(hostname || "")
+            .trim()
+            .toLowerCase()
+            .replace(/^\[|\]$/g, "");
+          if (!host) return false;
+          if (host === "localhost" || host.slice(-10) === ".localhost" || host.slice(-6) === ".local") {
+            return true;
+          }
+          if (host === "::1" || host === "0:0:0:0:0:0:0:1") return true;
+          var m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+          if (m) {
+            var a = +m[1];
+            var b = +m[2];
+            var c = +m[3];
+            var d = +m[4];
+            if ([a, b, c, d].some(function (n) {
+              return !Number.isInteger(n) || n < 0 || n > 255;
+            })) {
+              return false;
+            }
+            if (a === 127) return true;
+            if (a === 10) return true;
+            if (a === 192 && b === 168) return true;
+            if (a === 172 && b >= 16 && b <= 31) return true;
+            if (a === 169 && b === 254) return true;
+            return false;
+          }
+          if (host.indexOf(":") !== -1) {
+            if (host.slice(0, 2) === "fc" || host.slice(0, 2) === "fd") return true;
+            if (/^fe[89ab]/.test(host)) return true;
+          }
+          return false;
+        }
+
+        function validateTarget(url) {
+          var raw = typeof url === "string" ? url.trim() : "";
+          if (!raw) return { ok: false, error: "invalid-target" };
+          var parsed;
+          try {
+            parsed = new URL(raw);
+          } catch (_) {
+            return { ok: false, error: "invalid-target" };
+          }
+          if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            return { ok: false, error: "invalid-target" };
+          }
+          if (!isPrivateOrLoopbackHostname(parsed.hostname)) {
+            return { ok: false, error: "non-private-target" };
+          }
+          return { ok: true, url: raw };
+        }
+
+        function decodeFragment(fragment) {
+          var raw = String(fragment || "").replace(/^#/, "").trim();
+          if (!raw) return { ok: false, error: "missing-fragment" };
+          var m = /^v1\.([A-Za-z0-9_-]+)$/.exec(raw);
+          if (!m) return { ok: false, error: "unsupported-version" };
+          try {
+            var b64 = m[1].replace(/-/g, "+").replace(/_/g, "/");
+            while (b64.length % 4) b64 += "=";
+            var json = atob(b64);
+            var parsed = JSON.parse(json);
+            if (!parsed || parsed.v !== 1 || typeof parsed.u !== "string") {
+              return { ok: false, error: "invalid-payload" };
+            }
+            var target = validateTarget(parsed.u.trim());
+            if (!target.ok) return target;
+            if (parsed.e != null) {
+              var e = Number(parsed.e);
+              if (!isFinite(e)) return { ok: false, error: "invalid-expiry" };
+              if (Math.floor(Date.now() / 1000) > e) return { ok: false, error: "expired" };
+            }
+            return { ok: true, url: target.url };
+          } catch (err) {
+            return { ok: false, error: "invalid-payload" };
+          }
+        }
+
+        var decoded = decodeFragment(location.hash);
+        if (!decoded.ok) {
+          var map = {
+            "missing-fragment": "This share link is incomplete. Ask the operator to re-run dashboard-broadcast.",
+            "unsupported-version": "This share link uses an unsupported format.",
+            "invalid-payload": "This share link could not be decoded.",
+            "invalid-target": "This share link has an invalid Mission Control URL.",
+            "non-private-target": "This share link targets a non-private host and was blocked.",
+            expired: "This share link expired. Ask the operator for a fresh link.",
+          };
+          fail(map[decoded.error] || "Could not open Mission Control.");
+          return;
+        }
+
+        openEl.href = decoded.url;
+        openEl.hidden = false;
+        statusEl.textContent = "Ready. Continue to Mission Control on your LAN.";
+        // Auto-navigate only for validated private/loopback targets; button remains if blocked.
+        try {
+          location.replace(decoded.url);
+        } catch (_) {
+          /* keep button */
+        }
+      })();
+    </script>
+  </body>
+</html>

package/dashboard/serve.mjs

@@ -10,6 +10,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, watch, writeFileSync
 import { createServer } from "node:http";
 import { dirname, extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { shareShellTokenRequired } from "./lib/broadcast-share.mjs";
 import {
   DEFAULT_HOST,
   REPO_ROOT_ENV,
@@ -423,8 +424,10 @@ const server = createServer((req, res) => {
     return;
   }
 
+  // Cosmetic share resolver shell (fragment holds LAN+token client-side).
+  // ADR: 2026-08-11_mission-control-broadcast-url-mask.md
   const auth = authorizeMissionControlRequest(req, url, {
-    tokenRequired: TOKEN_REQUIRED,
+    tokenRequired: shareShellTokenRequired(TOKEN_REQUIRED, req.method || "GET", path),
     expectedToken: AUTH_TOKEN,
   });
   if (!auth.ok) {
@@ -496,7 +499,8 @@ const server = createServer((req, res) => {
     return;
   }
 
-  const staticPath = resolveStaticPath(path);
+  const staticLookup = path === "/open" ? "/open.html" : path;
+  const staticPath = resolveStaticPath(staticLookup);
   if (!staticPath) {
     res.writeHead(404);
     res.end("Not found");

package/dashboard/start-broadcast.mjs

@@ -9,9 +9,14 @@
 
 import { execFileSync, execSync, spawn } from "node:child_process";
 import { existsSync, openSync } from "node:fs";
-import { platform } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  buildBroadcastShareUrl,
+  resolveShareBase,
+  resolveShareShowLan,
+  resolveShareTtlSec,
+} from "./lib/broadcast-share.mjs";
 import {
   BROADCAST_TOKEN_ENV,
   escapePerlDoubleQuoted,
@@ -21,10 +26,15 @@ import {
   listLanIPv4Addresses,
   normalizeAuthToken,
   resolveBindHost,
+  resolveContextConfigPath,
+  resolveSnapshotRepoRoot,
 } from "./lib/guards.mjs";
+import { openBrowser, readPreferredBrowserFromConfig } from "./lib/open-browser.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const ROOT = join(__dirname, "..");
+const KIT_ROOT = join(__dirname, "..");
+/** Workspace snapshots / preference config. Defaults to KIT_ROOT. */
+const ROOT = resolveSnapshotRepoRoot(process.env, KIT_ROOT);
 const SERVE = join(__dirname, "serve.mjs");
 const LOG = process.env.MISSION_CONTROL_LOG || "/tmp/mission-control-broadcast.log";
 const PORT = Number.parseInt(process.env.PORT || "3333", 10);
@@ -97,7 +107,7 @@ function detachStart(env) {
   if (hasSetsid()) {
     const out = openSync(LOG, "a");
     const child = spawn("setsid", ["node", SERVE], {
-      cwd: ROOT,
+      cwd: KIT_ROOT,
       detached: true,
       stdio: ["ignore", out, out],
       env,
@@ -107,7 +117,7 @@ function detachStart(env) {
   }
 
   // Escape @/$ so scoped package paths (node_modules/@scope/...) survive Perl qq.
-  const rootEsc = escapePerlDoubleQuoted(ROOT);
+  const rootEsc = escapePerlDoubleQuoted(KIT_ROOT);
   const serveEsc = escapePerlDoubleQuoted(SERVE);
   const logEsc = escapePerlDoubleQuoted(LOG);
   const hostEsc = escapePerlDoubleQuoted(String(env.HOST));
@@ -129,7 +139,7 @@ function detachStart(env) {
   ].join(" ");
 
   const child = spawn("perl", ["-e", perl], {
-    cwd: ROOT,
+    cwd: KIT_ROOT,
     detached: true,
     stdio: "ignore",
     env,
@@ -148,24 +158,6 @@ async function waitReady(urls) {
   return null;
 }
 
-function openBrowser(url) {
-  const os = platform();
-  try {
-    if (os === "darwin") {
-      spawn("open", [url], { detached: true, stdio: "ignore" }).unref();
-      return true;
-    }
-    if (os === "win32") {
-      spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" }).unref();
-      return true;
-    }
-    spawn("xdg-open", [url], { detached: true, stdio: "ignore" }).unref();
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 async function main() {
   const { env, host, token } = resolveBroadcastEnv();
   if (isLoopbackBindHost(host)) {
@@ -203,14 +195,43 @@ async function main() {
     console.log(`Mission Control broadcast already listening on port ${PORT}`);
   }
 
+  const shareBase = resolveShareBase(process.env);
+  let shareUrl = null;
+  if (shareBase != null) {
+    try {
+      shareUrl = buildBroadcastShareUrl(displayUrl, {
+        base: shareBase,
+        ttlSec: resolveShareTtlSec(process.env),
+      });
+    } catch (err) {
+      // Non-RFC1918 primary LAN (Tailscale 100.64/10, public/DMZ) cannot encode into
+      // the share fragment allowlist — degrade to LAN/token print instead of exit 1.
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`Share URL skipped (${msg}). Printing LAN/token only.`);
+      shareUrl = null;
+    }
+  }
+  const showLan = resolveShareShowLan(process.env);
+  const openTarget = shareUrl || displayUrl;
+
   console.log("");
   console.log("  Mission Control (LAN broadcast)");
   console.log(`  Bind:  ${host}:${PORT}`);
+  if (shareUrl) {
+    console.log(`  Share: ${shareUrl}`);
+  }
   console.log(`  Token: ${token}`);
-  for (const ip of listLanIPv4Addresses()) {
-    console.log(`  LAN:   http://${ip}:${PORT}/?token=${encodeURIComponent(token)}`);
+  if (showLan || !shareUrl) {
+    for (const ip of listLanIPv4Addresses()) {
+      console.log(`  LAN:   http://${ip}:${PORT}/?token=${encodeURIComponent(token)}`);
+    }
+    console.log(`  Local: http://127.0.0.1:${PORT}/?token=${encodeURIComponent(token)}`);
+  }
+  if (shareUrl) {
+    console.log(
+      "  Share is a cosmetic Mission Kit (or BYO) link; phone must still reach this LAN.",
+    );
   }
-  console.log(`  Local: http://127.0.0.1:${PORT}/?token=${encodeURIComponent(token)}`);
   console.log("  Config writes stay loopback-only. Stop: kill the LISTEN pid on this port.");
   console.log("  Firewall: allow inbound TCP on this port for your LAN profile if needed.");
   console.log("");
@@ -218,10 +239,32 @@ async function main() {
   if (process.env.MISSION_CONTROL_NO_OPEN === "1") {
     return;
   }
-  if (openBrowser(displayUrl)) {
-    console.log("Opened primary URL in the default browser.");
-  } else {
-    console.log("Open a LAN URL above on your phone/tablet browser.");
+  let configValue = null;
+  const cfg = resolveContextConfigPath(ROOT, { existsSync });
+  if (cfg.ok) {
+    configValue = readPreferredBrowserFromConfig(cfg.path);
+  }
+  const result = openBrowser(openTarget, { configValue });
+  if (result.opened) {
+    if (result.reason === "preferred-fallback") {
+      console.log(
+        shareUrl
+          ? "Preferred browser failed; opened share URL with the OS default."
+          : "Preferred browser failed; opened primary URL with the OS default.",
+      );
+    } else {
+      console.log(
+        shareUrl
+          ? "Opened share URL in the preferred browser (or OS default)."
+          : "Opened primary URL in the preferred browser (or OS default).",
+      );
+    }
+  } else if (result.reason !== "no-open") {
+    console.log(
+      shareUrl
+        ? "Open the Share URL above on your phone/tablet browser."
+        : "Open a LAN URL above on your phone/tablet browser.",
+    );
   }
 }