@tokenoftrust/cli 1.4.0 → 1.4.1

package/bin/tot.mjs

@@ -16,8 +16,11 @@
  *   tot preview               push your store to a reviewable preview   ← built (validate + push preview ref; MCP preview_status read-back). `submit`/`deploy` are teaching aliases.
  *   tot ship                  publish the current green aggregate live  ← built (GET/POST /api/changes/ship → b09 orchestrator; exact plan + y/N confirm; waits for VERIFIED live truth)
  *   tot accept / tot merge    queue a PR into the preview aggregate      ← built (b08: plan + y/N confirm → POST /api/changes/integrate = b07 queue enqueue; NO merge-to-main, NO go-live; refuses non-TTY without --yes)
+ *   tot sync                  fetch `preview` + merge it into your branch ← built (b16: the common accept-conflict recovery path; local-only, stops safely on conflict)
  *   tot rollback [<version>]  instant re-point to a prior live version  ← built (u3 promotion_status/promotion_rollback seam; diff + y/N confirm; refuses non-TTY / ineligible)
  *   tot pr                    list / view / close your candidate PRs    ← built (candidate_status/candidate_close; gh-pr-shaped)
+ *   tot branches              full branch-cleanup report (every branch, not just open PRs)  ← built (b14: candidate_list)
+ *   tot cleanup               owner-confirmed branch GC (deletes terminal branches only)     ← built (b14: candidate_list + candidate_delete; --dry-run classifies only)
  *   tot doctor                check this machine is ready
  *   tot ideas                 copy-paste AI prompts that reliably wow
  *   tot feedback              send a note to ToT + your recent CLI activity  ← built (activity-log.mjs → feedback_submit MCP tool)
@@ -37,6 +40,7 @@ import { readFileSync } from "node:fs";
 import { detectContext } from "../src/context.mjs";
 import { printError } from "../src/errors.mjs";
 import { recordActivity, redactArgs } from "../src/activity-log.mjs";
+import { emitActivity, capRendered } from "../src/activity.mjs";
 import { maybeNotifyUpdate } from "../src/update-check.mjs";
 
 const BUILD_ORDER = ["clone", "validate", "dev", "preview"];
@@ -66,10 +70,15 @@ tot — Token of Trust developer CLI
   tot preview               push your store to a reviewable preview
   tot ship                  publish the tenant's current green aggregate live (plan → confirm → ship)
   tot accept / tot merge    queue a PR into the preview aggregate — operator verb, no go-live (plan → confirm → integrate)
+  tot sync                  fetch \`preview\` and merge it into your local branch (accept-conflict recovery)
   tot rollback [<version>]  instant re-point to a prior live version (list → confirm → rollback)
+  tot revert --preview <PR|sha>  remove already-integrated content from the preview aggregate via a new revert commit — no force-reset (plan → confirm → revert)
+  tot hotfix --pr <N>       OWNER-ONLY exception: release an urgent fix from main to live, bypassing unshipped preview work (plan → confirm → release → auto forward-integrate)
   tot retire                evict a candidate PR's preview to reclaim space — operator verb, rebuildable (plan → confirm → evict)
   tot go-live               cut the apex domain over to the storefront (readiness → confirm → cutover)
   tot pr                    list / view / close your candidate PRs
+  tot branches              full branch-cleanup report — every branch, any PR state, cleanup eligibility
+  tot cleanup               owner-confirmed branch GC (--dry-run to classify only; deletes terminal branches only)
   tot doctor                check this machine is ready
   tot ideas                 copy-paste AI prompts that reliably wow
   tot feedback "<msg>"      send feedback to Token of Trust (attaches recent activity)
@@ -146,6 +155,15 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  // Plumbing, not a developer-facing verb (like git's own credential helpers,
+  // never listed in `git help`) — `tot clone` configures it as this checkout's
+  // `credential.helper`, and git alone invokes it (get/store/erase) on every
+  // fetch/push. See src/commands/git-credential.mjs's header (unit u10).
+  if (cmd === "git-credential") {
+    const { run } = await import("../src/commands/git-credential.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "validate") {
     const { run } = await import("../src/commands/validate.mjs");
     return run(rest, ctx);
@@ -184,11 +202,42 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  // `sync` is the common accept-conflict recovery path (P1 item 12): fetches the
+  // protected `preview` branch and merges it into the developer's local branch so
+  // they can resolve locally, then re-`tot preview`. Purely local — no push, no
+  // MCP call, never touches the shared `preview`/`main` refs themselves. See
+  // sync.mjs's header for the full contract.
+  if (cmd === "sync") {
+    const { run } = await import("../src/commands/sync.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "rollback") {
     const { run } = await import("../src/commands/rollback.mjs");
     return run(rest, ctx);
   }
 
+  // `revert --preview <PR|integration-sha>` removes already-integrated content from
+  // the protected `preview` aggregate via a NEW auditable revert commit (b21) — NO
+  // force-reset, NO touch to main/live. Backed by POST /api/changes/revert (b07's
+  // TenantIntegrationQueue.enqueueRevert). To undo something already LIVE, that's
+  // `tot rollback`, not this. See revert.mjs's header.
+  if (cmd === "revert") {
+    const { run } = await import("../src/commands/revert.mjs");
+    return run(rest, ctx);
+  }
+
+  // `hotfix --pr <N>` is the OWNER-ONLY EXCEPTION lane (b22): release an urgent fix
+  // from `main` to live while `preview` still holds other unshipped work, EXCLUDING
+  // that unshipped preview head, then automatically forward-integrate main → preview
+  // and re-validate. It is DELIBERATELY a distinct verb — never a `--base main` flag
+  // on `tot ship` (which publishes the whole green preview aggregate). Backed by
+  // GET/POST /api/changes/hotfix → b22's HotfixOrchestrator. See hotfix.mjs's header.
+  if (cmd === "hotfix") {
+    const { run } = await import("../src/commands/hotfix.mjs");
+    return run(rest, ctx);
+  }
+
   // `retire` evicts a candidate PR's hosted preview to reclaim space (unit U7) —
   // a DISTINCT operator verb from `accept`/reject: retire touches no change
   // lifecycle and is reversible-by-rebuild (`tot preview build`). See retire.mjs.
@@ -207,6 +256,24 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  // `branches` is the FULL branch-cleanup report (every branch, any PR state) —
+  // distinct from `tot pr list`, which only shows OPEN PRs (P1 item 9). Read-only;
+  // always safe to run, and the report `tot cleanup` reuses before deleting anything.
+  if (cmd === "branches") {
+    const { run } = await import("../src/commands/branches.mjs");
+    return run(rest, ctx);
+  }
+
+  // `cleanup` is owner-confirmed BRANCH GC (P1 items 9/10) — an irreversible git-ref
+  // delete, distinct from `tot retire`'s hosted-preview eviction (rebuildable, no
+  // branch touched). `--dry-run` classifies and prints; it never deletes. Age alone
+  // never makes a branch eligible; main/preview are always kept; orphans are
+  // quarantined, never auto-deleted. See cleanup.mjs's header.
+  if (cmd === "cleanup") {
+    const { run } = await import("../src/commands/cleanup.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "app") {
     const { run } = await import("../src/commands/app/index.mjs");
     return run(rest, ctx);
@@ -238,12 +305,39 @@ async function dispatch(cmd, rest, ctx) {
   return 2;
 }
 
+/**
+ * The safe `subcommand` value for a command's activity event. Only the fixed
+ * sub-dispatcher verbs (e.g. `app scaffold` / `app dev`) are surfaced — an
+ * arbitrary positional (a tenant name, a path, a code) is NEVER used, so the
+ * activity `subcommand` field can't carry PII even before redaction. Returns
+ * undefined for every command without a fixed subcommand vocabulary.
+ */
+function safeSubcommand(cmd, rest) {
+  if (cmd === "app") {
+    const sub = rest.find((t) => t && !t.startsWith("-"));
+    if (sub === "scaffold" || sub === "dev") return sub;
+  }
+  return undefined;
+}
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   const ctx = detectContext();
   const startedAt = Date.now();
+  const command = cmd || "(none)";
+  const subcommand = safeSubcommand(cmd, rest);
   let code = 0;
   let errMsg = null;
+
+  // D3: emit `cli.command.invoked` on start — best-effort, a SILENT no-op without a
+  // hosted-bridge credential (never a network call / never blocks). Fired without
+  // await so it adds no latency to the command; settled alongside the result below.
+  const invokedEmit = emitActivity({
+    action: "cli.command.invoked",
+    outcome: { status: "invoked" },
+    payload: { args: { command, ...(subcommand ? { subcommand } : {}), cliVersion: VERSION, node: process.version } },
+  });
+
   try {
     code = await dispatch(cmd, rest, ctx);
     return code;
@@ -251,17 +345,35 @@ async function main() {
     errMsg = e?.message || String(e);
     throw e;
   } finally {
+    const exitCode = errMsg ? 1 : (code ?? 0);
+    const durationMs = Date.now() - startedAt;
     // Best-effort activity breadcrumb (never throws, never blocks). `feedback`'s own
     // free-text message is omitted — it's user-typed and belongs only in the report.
     recordActivity({
       ts: new Date().toISOString(),
       v: VERSION,
-      cmd: cmd || "(none)",
+      cmd: command,
       args: cmd === "feedback" ? ["«omitted»"] : redactArgs(rest),
-      code: errMsg ? 1 : (code ?? 0),
-      ms: Date.now() - startedAt,
+      code: exitCode,
+      ms: durationMs,
       ...(errMsg ? { err: String(errMsg).slice(0, 200) } : {}),
     });
+    // D3: emit `cli.command.result` (exit code + duration + a bounded/redacted
+    // rendered field). The house-style error text is capped + run through the JS
+    // redaction mirror; per the D0 catalog the `cli.*` rendered lane is empty-
+    // allowlisted, so it's DROPPED by design (the safe default for a high-volume
+    // action) — the emit path still exercises the mirror. Bounded-await here (with
+    // the invoked emit) so a live bridge flushes before the process exits; a no-op
+    // when there's no credential.
+    const resultEmit = emitActivity({
+      action: "cli.command.result",
+      outcome: { status: errMsg ? "failed" : "succeeded", durationMs },
+      payload: {
+        args: { command, ...(subcommand ? { subcommand } : {}), cliVersion: VERSION, exitCode, durationMs },
+        ...(errMsg ? { rendered: { output: capRendered(errMsg) } } : {}),
+      },
+    });
+    await Promise.allSettled([invokedEmit, resultEmit]);
     // Nudge if a newer/unsupported version exists (drawn from cache — instant),
     // and kick a detached registry refresh if stale. Never throws, never blocks.
     maybeNotifyUpdate(VERSION);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/activity.mjs

@@ -0,0 +1,378 @@
+/**
+ * emitActivity — the CLI's operational-activity emitter (card D3).
+ *
+ * This is a hand-maintained JS MIRROR of the D0 actor×action contract that lives,
+ * in TypeScript, in `packages/public-runtime/src/activity/` (event.ts / catalog.ts
+ * / redaction.ts). The CLI is published to npm STANDALONE and is deliberately pure
+ * JS with NO dependency on `@tot/public-runtime` (a TS package) — see that module's
+ * README ("Consuming this from the downstream cards → D3"). So instead of importing
+ * the contract, we mirror the slice of it the CLI needs, and a keep-in-step test
+ * (activity-mirror.test.mjs) fails LOUDLY the moment this mirror drifts from the TS
+ * source of truth (the same discipline as no-gitea-links.test.mjs).
+ *
+ * What this mirrors, exactly:
+ *   • the ActivityEvent envelope shape + ACTIVITY_SCHEMA_VERSION + newEventId()
+ *   • the CLI-relevant subset of ACTION_CATALOG (the `cli.*` action keys + their
+ *     default-deny argsAllow/renderedAllow allowlists)
+ *   • the redaction contract (REDACTION_MARKER, MAX_VALUE_LEN, the VALUE_CANARIES,
+ *     the KEY_NAME_CANARY, and redactPayload/createActivityEvent) — byte-for-byte,
+ *     so a value that the server-side contract would scrub is scrubbed here too.
+ * If you add a `cli.*` action, change an allowlist, or touch a canary in the TS
+ * source, you MUST update this file in lockstep — the keep-in-step test enforces it.
+ *
+ * Transport + gate (generalized from the obstacle beacon, obstacle-beacon.cjs):
+ *   emitActivity() is a SILENT NO-OP without a bridge credential configured — it
+ *   never makes a network call and never fails/blocks a command when the developer
+ *   isn't connected to a hosted /dev bridge (a bare `tot login`, an older session,
+ *   CI, the `--sample` path). With a credential it POSTs the redacted envelope to
+ *   the SAME `<activityUrl>/api/dev/activity` endpoint the obstacle beacon and the
+ *   dev heartbeat already use — best-effort, bounded by a hard timeout, and fully
+ *   swallowed so telemetry can never disrupt or delay the developer's command.
+ *
+ * Dependency-free (node: builtins + global fetch, Node ≥22).
+ */
+import { createHash } from "node:crypto";
+import { defaultCredentialsPath, readCredentials } from "./token-store.mjs";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Envelope (mirror of event.ts)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Envelope contract version — MIRROR of event.ts ACTIVITY_SCHEMA_VERSION. */
+export const ACTIVITY_SCHEMA_VERSION = 1;
+
+/** Node-native UUID v4 (Node ≥22 has globalThis.crypto). Mirror of event.ts newEventId(). */
+export function newEventId() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") return c.randomUUID();
+  // Fallback (should never be reached on a supported Node) — node:crypto.
+  return createHash("sha256").update(String(Math.random()) + Date.now()).digest("hex").slice(0, 32);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Action catalog — the CLI-relevant SUBSET (mirror of the `cli.*` keys in catalog.ts).
+//
+// Keep this in lockstep with packages/public-runtime/src/activity/catalog.ts. Only
+// the `cli.*` domain is mirrored here (the CLI never emits server/ui actions); the
+// keep-in-step test asserts that (a) this set is EXACTLY the `cli.*` keys in the TS
+// catalog and (b) each argsAllow/renderedAllow matches the TS entry.
+// ─────────────────────────────────────────────────────────────────────────────
+export const CLI_ACTION_CATALOG = {
+  "cli.command.invoked": {
+    argsAllow: ["command", "subcommand", "cliVersion", "node"],
+    renderedAllow: [],
+  },
+  "cli.command.result": {
+    argsAllow: ["command", "subcommand", "cliVersion", "exitCode", "durationMs"],
+    renderedAllow: [],
+  },
+  "cli.obstacle.reported": {
+    argsAllow: ["kind", "have", "need", "cliVersion"],
+    renderedAllow: [],
+  },
+  "cli.signin.requested": {
+    argsAllow: ["cliVersion"],
+    renderedAllow: [],
+  },
+};
+
+/** All CLI action keys as a runtime array. */
+export const CLI_ACTION_KEYS = Object.keys(CLI_ACTION_CATALOG);
+
+/** Deny-by-default guard — is this an allowlisted CLI action key? */
+export function isCliActionKey(v) {
+  return typeof v === "string" && Object.prototype.hasOwnProperty.call(CLI_ACTION_CATALOG, v);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Redaction contract (mirror of redaction.ts) — MUST match byte-for-byte.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Marker stored in place of a value that tripped a canary. Mirror of REDACTION_MARKER. */
+export const REDACTION_MARKER = "«redacted»";
+/** Cap on a stored rendered/arg string. Mirror of MAX_VALUE_LEN. */
+export const MAX_VALUE_LEN = 512;
+
+/**
+ * Secret/PII VALUE canaries — MIRROR of redaction.ts VALUE_CANARIES. The regex
+ * SOURCES here must stay identical to the TS side; the keep-in-step test compares
+ * them literally.
+ */
+export const VALUE_CANARIES = [
+  { label: "private_key", re: /-----BEGIN(?: [A-Z]+)? PRIVATE KEY-----/ },
+  { label: "jwt", re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]+/ },
+  { label: "bearer", re: /\bBearer\s+[A-Za-z0-9._~+/-]{12,}=*/i },
+  { label: "aws_access_key", re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { label: "gh_token", re: /\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}/ },
+  { label: "slack_token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/ },
+  { label: "openai_key", re: /\bsk-[A-Za-z0-9]{20,}/ },
+  { label: "email", re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/ },
+  { label: "card_number", re: /\b(?:\d[ -]?){13,19}\b/ },
+  { label: "phone", re: /\b\+?\d[\d ().-]{9,}\d\b/ },
+  { label: "high_entropy", re: /(?:^|[^A-Za-z0-9_-])[A-Za-z0-9_-]{28,}(?:$|[^A-Za-z0-9_-])/ },
+];
+
+/** Secret-looking KEY NAMES — dropped outright. MIRROR of redaction.ts KEY_NAME_CANARY. */
+export const KEY_NAME_CANARY =
+  /(?:secret|token|passwd|password|authorization|api[_-]?key|private[_-]?key|credential|cookie|session|bearer|jwt)/i;
+
+function isPrimitive(v) {
+  const t = typeof v;
+  return t === "string" || t === "number" || t === "boolean";
+}
+
+/** Scan a stringified value against the value canaries. Mirror of scanValueCanary. */
+export function scanValueCanary(value) {
+  for (const c of VALUE_CANARIES) if (c.re.test(value)) return c.label;
+  return undefined;
+}
+
+function redactLane(lane, raw, allow, hits) {
+  if (!raw) return undefined;
+  const allowSet = new Set(allow);
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (KEY_NAME_CANARY.test(key)) {
+      hits.push({ lane, key, reason: "key_name_canary" });
+      continue;
+    }
+    if (!allowSet.has(key)) {
+      hits.push({ lane, key, reason: "not_allowlisted" });
+      continue;
+    }
+    if (!isPrimitive(value)) {
+      hits.push({ lane, key, reason: "non_primitive" });
+      continue;
+    }
+    const str = String(value).slice(0, MAX_VALUE_LEN);
+    const canary = scanValueCanary(str);
+    if (canary) {
+      hits.push({ lane, key, reason: "value_canary", canary });
+      out[key] = REDACTION_MARKER;
+      continue;
+    }
+    out[key] = typeof value === "string" ? str : value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Apply the redaction contract to a raw payload for a CLI action. Pure. Mirror of
+ * redaction.ts redactPayload (restricted to the CLI catalog). An unknown action
+ * yields an empty payload (deny-all).
+ */
+export function redactPayload(action, raw) {
+  const hits = [];
+  const spec = CLI_ACTION_CATALOG[action];
+  if (!spec) {
+    if (raw?.args) for (const k of Object.keys(raw.args)) hits.push({ lane: "args", key: k, reason: "unknown_action" });
+    if (raw?.rendered) for (const k of Object.keys(raw.rendered)) hits.push({ lane: "rendered", key: k, reason: "unknown_action" });
+    return { payload: undefined, report: { keptArgs: [], keptRendered: [], hits, canaryTripped: false } };
+  }
+  const args = redactLane("args", raw?.args, spec.argsAllow, hits);
+  const renderedRaw = redactLane("rendered", raw?.rendered, spec.renderedAllow, hits);
+  const rendered = renderedRaw
+    ? Object.fromEntries(Object.entries(renderedRaw).map(([k, v]) => [k, String(v)]))
+    : undefined;
+  const payload = args || rendered ? { ...(args ? { args } : {}), ...(rendered ? { rendered } : {}) } : undefined;
+  return {
+    payload,
+    report: {
+      keptArgs: args ? Object.keys(args) : [],
+      keptRendered: rendered ? Object.keys(rendered) : [],
+      hits,
+      canaryTripped: hits.some((h) => h.reason === "value_canary"),
+    },
+  };
+}
+
+/**
+ * The safe constructor — mirror of redaction.ts createActivityEvent. Fills v/id/at
+ * and runs the raw payload through redactPayload() so the returned event's payload
+ * is already default-denied + canary-scanned. Throws only on an out-of-catalog
+ * (non-`cli.*`) action — a programming error.
+ */
+export function createActivityEvent({ action, actor, source = "cli", outcome, scope, payload, at, id }) {
+  if (!isCliActionKey(action)) throw new Error(`activity: unknown CLI action "${action}" (not in the CLI mirror catalog)`);
+  const { payload: redacted, report } = redactPayload(action, payload);
+  const event = {
+    v: ACTIVITY_SCHEMA_VERSION,
+    id: id ?? newEventId(),
+    at: at ?? new Date().toISOString(),
+    actor,
+    action,
+    source,
+    scope: scope ?? {},
+    outcome,
+    ...(redacted ? { payload: redacted } : {}),
+  };
+  return { event, report };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Bridge resolution + emit
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Hard cap on how long a single emit may take before it's abandoned (never blocks a command). */
+const EMIT_TIMEOUT_MS = 1500;
+
+/**
+ * The ONE activity-telemetry kill switch (card D8) — the SAME flag name the server
+ * honours (`apps/storefront/src/lib/activity/killSwitch.ts`). Set
+ * `ACTIVITY_TELEMETRY_DISABLED=1` (or true/yes/on) and every CLI emit becomes a silent
+ * no-op — no build, no redaction, no network — while the command itself runs unchanged
+ * (fail-open). Unset ⇒ telemetry enabled (the normal state).
+ */
+export const ACTIVITY_KILL_SWITCH_FLAG = "ACTIVITY_TELEMETRY_DISABLED";
+export function isActivityDisabled(env = process.env) {
+  const v = env && env[ACTIVITY_KILL_SWITCH_FLAG];
+  return typeof v === "string" && ["1", "true", "yes", "on"].includes(v.trim().toLowerCase());
+}
+
+/**
+ * Resolve the local→hosted activity-bridge credential, or null when none is
+ * configured (→ emitActivity is a no-op). Mirrors the resolution the obstacle
+ * beacon (obstacle.mjs) and the heartbeat (dev-heartbeat.mjs) use: the env override
+ * `TOT_DEV_ACTIVITY_URL`/`TOT_DEV_ACTIVITY_TOKEN` (threaded to runner-spawning
+ * paths) wins, else the `activityUrl`/`activityToken` cached in ~/.tot/credentials.json.
+ */
+export function resolveActivityBridge(env = process.env) {
+  const url = env.TOT_DEV_ACTIVITY_URL;
+  const token = env.TOT_DEV_ACTIVITY_TOKEN;
+  if (url && token) return { url, token };
+  try {
+    const creds = readCredentials(defaultCredentialsPath(env));
+    if (creds?.activityUrl && creds?.activityToken) {
+      return { url: creds.activityUrl, token: creds.activityToken };
+    }
+  } catch {
+    /* best-effort — no bridge */
+  }
+  return null;
+}
+
+/**
+ * The event's actor — kind `dev` (or `agent` when the caller signals an automated
+ * run) with an OPAQUE, non-reversible id, per the D0 contract (actor.id in the core
+ * zone is NEVER raw PII). Until the canonical pseudonymization salt lands (an open
+ * question owned by D1/D4 — see redaction.ts header), we derive the id from an
+ * already-opaque handle: the masked emailHint if present, else a one-way hash of the
+ * bridge token, else "anonymous". Never reversible, never raw PII.
+ */
+export function resolveActor(env = process.env) {
+  const kind = env.TOT_ACTOR_KIND === "agent" ? "agent" : "dev";
+  let seed = "anonymous";
+  try {
+    const creds = readCredentials(defaultCredentialsPath(env));
+    if (creds?.emailHint) seed = `hint:${creds.emailHint}`;
+    else if (creds?.activityToken) seed = `tok:${creds.activityToken}`;
+  } catch {
+    /* fall through to anonymous */
+  }
+  const id = seed === "anonymous" ? "anonymous" : createHash("sha256").update(seed).digest("hex").slice(0, 16);
+  return { kind, id };
+}
+
+/**
+ * The scope threaded onto every CLI event — the storefront-minted invite→problem
+ * `traceId` from the credential cache, when present, so a CLI event and the server
+ * event it triggers share one trace (matching the existing feedback/heartbeat use).
+ */
+function resolveScope(env = process.env, extra = {}) {
+  const scope = { ...extra };
+  try {
+    const creds = readCredentials(defaultCredentialsPath(env));
+    if (creds?.traceId && !scope.traceId) scope.traceId = creds.traceId;
+  } catch {
+    /* best-effort */
+  }
+  return scope;
+}
+
+/**
+ * Emit one activity event. SILENT NO-OP without a bridge credential (returns
+ * `{ sent:false }`) — no network call, never throws, never blocks a command. With
+ * a credential it builds the redacted envelope (via createActivityEvent) and POSTs
+ * it best-effort to `<url>/api/dev/activity`, bounded by EMIT_TIMEOUT_MS.
+ *
+ * Returns `{ sent, event?, report? }` so callers/tests can assert what would be
+ * emitted without any network. `fetchImpl` and `bridge` are injectable for tests.
+ *
+ * @param {{ action: string, outcome: object, actor?: object, scope?: object,
+ *   payload?: object, source?: string, env?: NodeJS.ProcessEnv,
+ *   fetchImpl?: typeof fetch, bridge?: {url:string,token:string}|null }} input
+ * @returns {Promise<{sent:boolean, event?:object, report?:object}>}
+ */
+export async function emitActivity({
+  action,
+  outcome,
+  actor,
+  scope,
+  payload,
+  source = "cli",
+  env = process.env,
+  fetchImpl,
+  bridge,
+} = {}) {
+  try {
+    // Kill switch (D8): telemetry off ⇒ true no-op (no build/redaction/network),
+    // fail-open — the command is unaffected.
+    if (isActivityDisabled(env)) return { sent: false, disabled: true };
+    const resolvedBridge = bridge !== undefined ? bridge : resolveActivityBridge(env);
+    // Build the redacted event even when we won't send it — so a caller/test can
+    // inspect the exact shape, and so redaction always runs on the emit path.
+    const { event, report } = createActivityEvent({
+      action,
+      actor: actor ?? resolveActor(env),
+      source,
+      outcome,
+      scope: resolveScope(env, scope ?? {}),
+      payload,
+    });
+    if (!resolvedBridge) return { sent: false, event, report };
+
+    const doFetch = fetchImpl || globalThis.fetch;
+    if (typeof doFetch !== "function") return { sent: false, event, report };
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), EMIT_TIMEOUT_MS);
+    if (typeof timer.unref === "function") timer.unref();
+    try {
+      await doFetch(`${String(resolvedBridge.url).replace(/\/+$/, "")}/api/dev/activity`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${resolvedBridge.token}`,
+        },
+        // `event: "activity"` tags the stream for the bridge/D4 ingest to route,
+        // alongside the D0 envelope. Best-effort — an older bridge that doesn't
+        // recognize it simply ignores the post.
+        body: JSON.stringify({ event: "activity", ...event }),
+        signal: controller.signal,
+      });
+    } catch {
+      /* best-effort — a failed/offline/aborted post never disrupts the command */
+    } finally {
+      clearTimeout(timer);
+    }
+    return { sent: true, event, report };
+  } catch {
+    // Absolutely never throw into a command's control flow.
+    return { sent: false };
+  }
+}
+
+/**
+ * Cap + surface a bit of rendered output for a command-result event. The full raw
+ * stdout is NEVER stored — this caps to MAX_VALUE_LEN and hands the string to the
+ * redaction mirror via payload.rendered. NB the `cli.command.*` actions carry an
+ * EMPTY renderedAllow in the D0 catalog, so this string is DROPPED at redaction by
+ * design (the safe default for a high-volume action) — running it through the
+ * mirror is the belt-and-suspenders the contract prescribes, and keeps the emit
+ * path honest if the allowlist ever opens. Pure.
+ */
+export function capRendered(text) {
+  const s = String(text ?? "").trim();
+  if (!s) return undefined;
+  return s.slice(0, MAX_VALUE_LEN);
+}