@tokenoftrust/storefront-runner 2.2.86 → 2.2.87

package/apps/storefront/src/config/declaredTenantConfig.ts

@@ -0,0 +1,94 @@
+/**
+ * The render-time read of a tenant's declared platform config (`.tot/config.json`
+ * → siteType/compliance/capabilities/features; see
+ * `@tot/public-runtime/declared-tenant-config`). Every render applies it the same
+ * way, on top of the resolved tenant record:
+ *
+ *   1. the checkout's own file in the build tree — what `tot dev` grafts in and
+ *      what the static-publish build materializes from the tenant repo;
+ *   2. the per-environment artifact the reconcile derived from the same file at the
+ *      reconciled commit — what the hosted Worker serves preview and live from.
+ *
+ * Both are the same file at the same commit, so a tenant renders identically on
+ * every surface; a field honored by one is honored by all.
+ */
+import {
+  applyDeclaredTenantConfig,
+  declaredTenantConfig,
+  declaredTenantConfigArtifactPath,
+  type DeclaredTenantConfig,
+} from "@tot/public-runtime/declared-tenant-config";
+import {
+  readPublishedArtifact,
+  readVersionArtifact,
+  tenantIdFromPath,
+  type CustomizationEnv,
+  type TenantConfig,
+} from "@tot/public-runtime";
+
+// The checkout's own `.tot/config.json`, read eagerly (tiny JSON). From src/config/
+// the repo root is four levels up; both tenant tiers are globbed, and the explicit
+// `.tot` literal matches the dotdir.
+const checkoutConfigFiles = import.meta.glob<Record<string, unknown>>(
+  ["../../../../tenants/*/.tot/config.json", "../../../../tenants/e2e/*/.tot/config.json"],
+  { eager: true, import: "default" },
+);
+
+/** dir id → that checkout's parsed `.tot/config.json`. */
+export function checkoutTotConfigs(): Map<string, Record<string, unknown>> {
+  const map = new Map<string, Record<string, unknown>>();
+  for (const [key, config] of Object.entries(checkoutConfigFiles)) {
+    const id = tenantIdFromPath(key);
+    if (id && config && typeof config === "object") map.set(id, config);
+  }
+  return map;
+}
+
+/** The declaration in the checkout's own `.tot/config.json`, or `{}` when it has none. */
+export function checkoutDeclaredTenantConfig(tenantId: string): DeclaredTenantConfig {
+  return declaredTenantConfig(checkoutConfigFiles[`../../../../tenants/${tenantId}/.tot/config.json`]
+    ?? checkoutConfigFiles[`../../../../tenants/e2e/${tenantId}/.tot/config.json`]);
+}
+
+/** The declaration the reconcile published for this environment, or `{}`. */
+export async function publishedDeclaredTenantConfig(
+  kvGet: (key: string) => Promise<string | null>,
+  tenantId: string,
+  env: CustomizationEnv,
+): Promise<DeclaredTenantConfig> {
+  const raw = await readPublishedArtifact(kvGet, tenantId, env, declaredTenantConfigArtifactPath(tenantId));
+  if (!raw) return {};
+  try {
+    return declaredTenantConfig(JSON.parse(raw));
+  } catch {
+    return {};
+  }
+}
+
+/** The declaration pinned to one immutable version (a candidate under review), or `{}`. */
+export async function versionDeclaredTenantConfig(
+  kvGet: (key: string) => Promise<string | null>,
+  tenantId: string,
+  versionId: string,
+): Promise<DeclaredTenantConfig> {
+  const raw = await readVersionArtifact(kvGet, tenantId, versionId, declaredTenantConfigArtifactPath(tenantId));
+  if (!raw) return {};
+  try {
+    return declaredTenantConfig(JSON.parse(raw));
+  } catch {
+    return {};
+  }
+}
+
+/** The tenant as it renders in `env`: its record with every declaration applied. */
+export async function withDeclaredTenantConfig(
+  tenant: TenantConfig,
+  kvGet: (key: string) => Promise<string | null>,
+  env: CustomizationEnv,
+): Promise<TenantConfig> {
+  const fromCheckout = applyDeclaredTenantConfig(tenant, checkoutDeclaredTenantConfig(tenant.tenant_id));
+  return applyDeclaredTenantConfig(
+    fromCheckout,
+    await publishedDeclaredTenantConfig(kvGet, tenant.tenant_id, env),
+  );
+}

package/apps/storefront/src/middleware/renderChain.ts

@@ -97,6 +97,7 @@ import {
 import { recordActivity } from "@/lib/activity/recordActivity";
 import { middlewareRewriteTargetV1 } from "./routeBranch.js";
 import { declaredTenantOrigins } from "@/lib/tenantOrigins";
+import { withDeclaredTenantConfig } from "@/config/declaredTenantConfig";
 import {
   applyInternalContentResponsePolicy,
   internalContentGrantMatchesPlan,
@@ -147,7 +148,7 @@ export interface RenderChainInput {
 export const TENANT_ORIGINS_CAPTURE_HEADER = "x-tot-tenant-origins";
 
 export async function runRenderChain(input: RenderChainInput): Promise<Response> {
-  const { context, next, host, url, tenant, basePath, renderPath, cache, kv } = input;
+  const { context, next, host, url, tenant: tenantRecord, basePath, renderPath, cache, kv } = input;
   const { request, locals } = context;
   const isInternalPublication = input.publicationRoute.action !== "fail-closed" &&
     input.publicationRoute.manifest.visibility === "internal";
@@ -177,7 +178,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // pin can only ever name its own version; a mismatched/expired/absent token
   // falls through to the normal channel-resolved read below, same fail-closed
   // posture as the `__preview` token.
-  const candidatePin = await resolveCandidateContentPin(url, tenant.tenant_id);
+  const candidatePin = await resolveCandidateContentPin(url, tenantRecord.tenant_id);
   // Per-developer AI-edit draft: the signed
   // tot_dev_draft cookie's mere PRESENCE opts the request out of the shared page
   // cache below (a draft view must never be cached publicly); it's verified —
@@ -192,7 +193,7 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   const nowSeconds = Math.floor(Date.now() / 1000);
   const customization = await resolveCustomizationEnv({
     isPreviewHost,
-    tenantId: tenant.tenant_id,
+    tenantId: tenantRecord.tenant_id,
     token: previewToken,
     secret: previewSecret,
     nowSeconds,
@@ -230,6 +231,16 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     if (isInternalPublication) applyInternalContentResponsePolicy(response.headers);
     return response;
   }
+
+  // The tenant as it renders in THIS environment: its record with the declared
+  // `.tot/config.json` fields applied (compliance, siteType, capabilities,
+  // features). Everything below — static bundle, notices, gates, features,
+  // capabilities — reads this, never the bare record.
+  const tenant = await withDeclaredTenantConfig(
+    tenantRecord,
+    kv ? (key: string) => kv.get(key) : async () => null,
+    customization.env,
+  );
   const publicationTimestamp = publicationSource.status === "selected"
     ? publicationSource.publicationTimestamp
     : exactPublicationTimestamp(await readEnv("TOT_PUBLICATION_TIMESTAMP"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.86",
+  "version": "2.2.87",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/package.json

@@ -19,6 +19,7 @@
     "./durable-assets": "./src/durable-assets.ts",
     "./retention-holds": "./src/retention-holds.ts",
     "./tenant-embed-defaults": "./src/tenant-embed-defaults.mjs",
+    "./declared-tenant-config": "./src/declared-tenant-config.mjs",
     "./integration/lifecycle-host-asset": "./src/integration/lifecycle-host-asset.mjs",
     "./integration/native-ga4-sandbox-asset": "./src/integration/native-ga4-sandbox-asset.mjs",
     "./integration/visitor-region": "./src/integration/visitor-region.mjs"

package/packages/public-runtime/src/declared-tenant-config.d.mts

@@ -0,0 +1,22 @@
+/** Types for the dependency-free declared-tenant-config module (declared-tenant-config.mjs). */
+import type { TenantConfig } from "./tenant.js";
+
+export type DeclaredTenantConfigField = "siteType" | "compliance" | "capabilities" | "features";
+export type DeclaredTenantConfig = Partial<Pick<TenantConfig, DeclaredTenantConfigField>>;
+
+export const DECLARED_TENANT_CONFIG_FIELDS: readonly DeclaredTenantConfigField[];
+export const TOT_CONFIG_KEYS: readonly string[];
+export const COMPLIANCE_KEYS: readonly string[];
+export const FEATURE_KEYS: readonly string[];
+export const SITE_TYPES_LIST: readonly string[];
+export function declaredTenantConfig(config: unknown): DeclaredTenantConfig;
+export function isEmptyDeclaredTenantConfig(declared: DeclaredTenantConfig | null | undefined): boolean;
+export function applyDeclaredTenantConfig<T extends Partial<Pick<TenantConfig, DeclaredTenantConfigField>>>(
+  tenant: T,
+  declared: DeclaredTenantConfig | null | undefined,
+): T;
+export function readDeclaredTenantConfigAt(
+  source: { readFile(path: string, ref: string): Promise<string | null> },
+  ref: string,
+): Promise<DeclaredTenantConfig>;
+export function declaredTenantConfigArtifactPath(tenantId: string): string;

package/packages/public-runtime/src/declared-tenant-config.mjs

@@ -0,0 +1,150 @@
+/**
+ * The tenant's declared platform config: the `.tot/config.json` fields that become
+ * TenantConfig fields on every surface that renders the tenant.
+ *
+ * `.tot/config.json` is the ONE declared source for these fields. Every reader goes
+ * through this module:
+ *   - `tot dev` and the static-publish build read the checkout's own file from the
+ *     build tree (apps/storefront/src/config/resolver.ts `declaredConfigFor`);
+ *   - the hosted Worker reads the per-environment artifact the reconcile derives from
+ *     the same file at the reconciled commit (`declaredTenantConfigArtifactPath`);
+ *   - `tot validate` refuses any top-level key not in `TOT_CONFIG_KEYS`, so a field
+ *     no surface reads cannot pass validation.
+ * All of them apply it with `applyDeclaredTenantConfig`, so a field honored on one
+ * surface is honored on all of them.
+ *
+ * Plain JS on purpose (same reason as embed-catalog.mjs): plain-`node` tooling and
+ * the CLI's parity test read it alongside the TypeScript runtime.
+ */
+
+/** `.tot/config.json` keys that become TenantConfig fields. */
+export const DECLARED_TENANT_CONFIG_FIELDS = Object.freeze([
+  "siteType",
+  "compliance",
+  "capabilities",
+  "features",
+]);
+
+/**
+ * Every top-level `.tot/config.json` key the platform reads: the reconcile mapping
+ * keys, the CLI's host hint, provenance markers (`sample` from `tot dev --sample`,
+ * `seed` from the tot-mcp repo seed), an editor's `$schema`, and the declared
+ * TenantConfig fields.
+ */
+export const TOT_CONFIG_KEYS = Object.freeze([
+  "$schema",
+  "tenant",
+  "scope",
+  "mappings",
+  "hostPlatform",
+  "sample",
+  "seed",
+  ...DECLARED_TENANT_CONFIG_FIELDS,
+]);
+
+/** Every `compliance` key the platform renders or enforces (ComplianceConfig, tenant.ts). */
+export const COMPLIANCE_KEYS = Object.freeze([
+  "ruleProfile",
+  "minAge",
+  "nicotineWarning",
+  "shippingRestriction",
+  "pactAct",
+  "adultSignature",
+  "prop65",
+  "purchaseLimit",
+  "stateEligibility",
+  "exciseTax",
+]);
+
+/** Every `features` key (TenantFeatures, tenant.ts). */
+export const FEATURE_KEYS = Object.freeze([
+  "catalog",
+  "productSearch",
+  "savedItems",
+  "quickView",
+  "newsletter",
+  "commerceSitemap",
+  "productJsonLd",
+  "ageGate",
+]);
+
+/** Every `siteType` value (SiteType, tenant.ts). */
+export const SITE_TYPES_LIST = Object.freeze(["commerce", "marketing"]);
+
+const SITE_TYPES = new Set(SITE_TYPES_LIST);
+
+const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * The declared TenantConfig fields from a parsed `.tot/config.json`. A field whose
+ * value has the wrong shape is omitted, never coerced (`tot validate` reports it).
+ *
+ * @param {unknown} config
+ */
+export function declaredTenantConfig(config) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  if (!isPlainObject(config)) return out;
+  const { siteType, compliance, capabilities, features } = /** @type {Record<string, unknown>} */ (config);
+  if (typeof siteType === "string" && SITE_TYPES.has(siteType)) out.siteType = siteType;
+  if (isPlainObject(compliance)) out.compliance = compliance;
+  if (isPlainObject(capabilities)) out.capabilities = capabilities;
+  if (isPlainObject(features)) out.features = features;
+  return out;
+}
+
+/** True when the declaration sets nothing. */
+export function isEmptyDeclaredTenantConfig(declared) {
+  return !declared || Object.keys(declared).length === 0;
+}
+
+/**
+ * Overlay a declaration onto a resolved tenant. `siteType` is replaced; the object
+ * fields merge key by key, so a declaration adds to — and can set individual keys
+ * of — what the platform record already carries, but never erases a key it omits.
+ *
+ * @template T
+ * @param {T} tenant
+ * @param {Record<string, unknown> | null | undefined} declared
+ * @returns {T}
+ */
+export function applyDeclaredTenantConfig(tenant, declared) {
+  if (isEmptyDeclaredTenantConfig(declared)) return tenant;
+  const out = /** @type {Record<string, unknown>} */ ({ ...tenant });
+  for (const field of DECLARED_TENANT_CONFIG_FIELDS) {
+    const value = declared[field];
+    if (value === undefined) continue;
+    out[field] = isPlainObject(value) && isPlainObject(out[field])
+      ? { ...out[field], ...value }
+      : value;
+  }
+  return /** @type {T} */ (out);
+}
+
+/**
+ * The declaration a tenant repo commits at `ref`, read through any source with the
+ * reconcile's `readFile(path, ref)` shape. `{}` when the file is absent or unreadable.
+ *
+ * @param {{ readFile(path: string, ref: string): Promise<string | null> }} source
+ * @param {string} ref
+ */
+export async function readDeclaredTenantConfigAt(source, ref) {
+  try {
+    const raw = await source.readFile(".tot/config.json", ref);
+    return raw ? declaredTenantConfig(JSON.parse(raw)) : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Artifact path of the declaration the reconcile derives by reading `.tot/config.json`,
+ * in the same colocated `tenants/<id>/…` space as theme/capabilities so it is
+ * pinned per version and resolved per environment like every other artifact.
+ *
+ * @param {string} tenantId
+ */
+export function declaredTenantConfigArtifactPath(tenantId) {
+  return `tenants/${tenantId}/tenant-config.json`;
+}

package/scripts/dev/port-lock.mjs

@@ -0,0 +1,109 @@
+// @ts-check
+/**
+ * Records which pid `tot dev` last bound a given port under, so a later
+ * invocation that finds the port busy can tell a STALE occupant (our own
+ * earlier `tot dev` process, no longer running — the socket just hasn't been
+ * released yet, or the process crashed without a clean shutdown) from a
+ * genuinely live one (a different, healthy server — ours or someone else's).
+ *
+ * Without this, `firstFreePort` silently drifts to the next port either way —
+ * fine for "someone else's server is using 4321", actively misleading after a
+ * crash: the developer's browser is still pointed at the old port, and nothing
+ * tells them the server they expect there isn't the one that just started
+ * (fb-1791304494289-ussj8l). Dependency-free (node:fs/os/path only) so it
+ * copies into the standalone runner like port-check.mjs.
+ */
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const PORT_LOCK_DIR = join(homedir(), ".tot", "run", "dev-ports");
+
+/** Record that `pid` (default: this process) is bound to `port`. Best-effort. */
+export function lockPort(port, { pid = process.pid, dir = PORT_LOCK_DIR } = {}) {
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, String(port)), String(pid));
+  } catch {
+    /* best-effort — a failed lock must never block `tot dev` from starting */
+  }
+}
+
+/** Release a port lock (best-effort; safe to call more than once). */
+export function unlockPort(port, { dir = PORT_LOCK_DIR } = {}) {
+  try {
+    rmSync(join(dir, String(port)), { force: true });
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** The pid last recorded as bound to `port`, or null when no lock is on file / unreadable. */
+export function readPortLock(port, { dir = PORT_LOCK_DIR } = {}) {
+  try {
+    const pid = Number(readFileSync(join(dir, String(port)), "utf8").trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Is a pid a live process? (signal 0 probe; EPERM = alive but not ours.) */
+export function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return /** @type {NodeJS.ErrnoException} */ (e)?.code === "EPERM";
+  }
+}
+
+/**
+ * Why is `requestedPort` unavailable?
+ *  - `{ kind: "ours", pid }` — an EARLIER `tot dev` session still holds it and is
+ *    still running. It may be wedged (a renderer crash leaves the server process
+ *    alive and bound), so the developer must be told which process to stop.
+ *  - `{ kind: "stale", pid }` — our own recorded occupant is gone; the socket is
+ *    lingering past a crash/kill.
+ *  - `{ kind: "other" }` — busy with no lock of ours: someone else's server.
+ *  - `null` — the port isn't busy right now.
+ * @param {number} requestedPort
+ * @param {{ isFree: (port:number)=>Promise<boolean>, pidAlive?: (pid:number)=>boolean, dir?: string }} deps
+ * @returns {Promise<{kind:"ours"|"stale", pid:number}|{kind:"other"}|null>}
+ */
+export async function classifyBusyPort(requestedPort, { isFree, pidAlive = processAlive, dir = PORT_LOCK_DIR }) {
+  if (await isFree(requestedPort)) return null;
+  const pid = readPortLock(requestedPort, { dir });
+  if (pid == null) return { kind: "other" };
+  return { kind: pidAlive(pid) ? "ours" : "stale", pid };
+}
+
+/**
+ * The line `tot dev` prints when it starts on `resolvedPort` because
+ * `requestedPort` was busy. Every case involving an earlier `tot dev` session
+ * says so and names the process, so a browser tab left on the old port is never
+ * silently a different server.
+ * @param {number} requestedPort
+ * @param {number} resolvedPort
+ * @param {{kind:"ours"|"stale", pid:number}|{kind:"other"}|null} busy
+ */
+export function busyPortMessage(requestedPort, resolvedPort, busy) {
+  const tab = `    A browser tab on :${requestedPort} is NOT this session — use the URL below.`;
+  if (busy?.kind === "ours") {
+    return (
+      `  ⚠ port ${requestedPort} is held by an earlier \`tot dev\` session that is still running ` +
+      `(pid ${busy.pid}) — starting on ${resolvedPort} instead.\n` +
+      `    If that session crashed or stopped reloading, stop it (\`kill ${busy.pid}\`) and restart to get ${requestedPort} back.\n` +
+      tab
+    );
+  }
+  if (busy?.kind === "stale") {
+    return (
+      `  ⚠ port ${requestedPort} is still held after an earlier \`tot dev\` session (pid ${busy.pid}) exited ` +
+      `— starting on ${resolvedPort} instead.\n` +
+      `    Find the holder with \`lsof -nP -iTCP:${requestedPort} -sTCP:LISTEN\` and stop it to get ${requestedPort} back.\n` +
+      tab
+    );
+  }
+  return `  ⚠ port ${requestedPort} was busy — starting on ${resolvedPort} instead.`;
+}

package/scripts/dev/standalone-graft-plan.mjs

@@ -0,0 +1,35 @@
+// @ts-check
+/**
+ * Pure planning for `tot dev --workspace` grafts: which checkout-relative paths
+ * get copied into the in-tree `tenants/<id>/` layout the app globs, and whether
+ * each is a file or a directory tree. Decision-only — scripts/tot-dev.mjs does
+ * the actual fs copy/backup/watch effects per planned entry.
+ */
+
+/**
+ * @param {Array<{workspace?: unknown, kind?: unknown}>} mappings the checkout's
+ *   own `.tot/config.json` `mappings` array (content/, public/, theme.json, …)
+ * @returns {{ workspace: string, isDir: boolean }[]}
+ */
+export function standaloneGraftPlan(mappings) {
+  const plan = [];
+  const seen = new Set();
+  for (const map of Array.isArray(mappings) ? mappings : []) {
+    const workspace = String(map?.workspace ?? "").replace(/\/+$/, "");
+    if (!workspace || seen.has(workspace)) continue;
+    seen.add(workspace);
+    plan.push({ workspace, isDir: map?.kind !== "file" });
+  }
+  // `.tot/config.json` is never itself one of the declared `mappings` (those map
+  // content/public/theme.json) but IS the tenant's own declared platform config
+  // — siteType/compliance/capabilities/features (see
+  // apps/storefront/src/config/devTenantSeed.ts TOT_CONFIG_TENANT_FIELDS and
+  // resolver.ts declaredConfigs()) — the same file
+  // scripts/tenant/materialize-tenant-content.mjs copies for a Gitea-sourced
+  // tenant. Graft it unconditionally so a regulated store's mandated notices
+  // resolve from the SAME declared config locally as they would once published.
+  if (!seen.has(".tot/config.json")) {
+    plan.push({ workspace: ".tot/config.json", isDir: false });
+  }
+  return plan;
+}

package/scripts/tot-dev.mjs

@@ -63,8 +63,10 @@ import { dirname, resolve, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveDevSourceRoot } from "./dev/tenant-source-root.mjs";
 import { tenantDirRelative, tenantDirSegments } from "./lib/tenant-dirs.mjs";
-import { firstFreePort } from "./dev/port-check.mjs";
+import { firstFreePort, isPortFree } from "./dev/port-check.mjs";
+import { busyPortMessage, classifyBusyPort, lockPort, unlockPort } from "./dev/port-lock.mjs";
 import { resync, startWatch } from "./dev/checkout-watch.mjs";
+import { standaloneGraftPlan } from "./dev/standalone-graft-plan.mjs";
 import { findMissingCtaIds } from "./tenant/validate.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -273,25 +275,18 @@ if (workspacePath) {
   console.log(`\n  tot dev — standalone (${tenant})`);
   console.log(`  checkout: ${wsRoot}`);
 
-  for (const map of mappings) {
-    // `workspace` is the checkout-relative prefix (e.g. "content/", "theme.json").
-    // COLOCATION: a tenant IS the repo-root dir `tenants/<id>/`, and the checkout
-    // (a `git subtree split --prefix=tenants/<id>` of that dir) has the SAME layout
-    // at its root — so the graft is an identity map: content/ -> tenants/<id>/content/,
-    // public/ -> tenants/<id>/public/, theme.json -> tenants/<id>/theme.json. We map
-    // structurally (ignoring any legacy `repo` field in the checkout's .tot/config.json).
-    const wsRel = String(map.workspace ?? "").replace(/\/+$/, "");
-    if (!wsRel) continue;
+  /**
+   * Graft one checkout path (`wsRel`, checkout-relative) into the in-tree
+   * `tenants/<tenant>/` layout the app globs, with the same move-aside/restore +
+   * watch-and-resync machinery every mapping gets. Returns true if grafted.
+   */
+  function graftOne(wsRel, isDir) {
     const repoRel = join(tenantDirRelative(tenant), wsRel);
 
     const source = resolve(wsRoot, wsRel); // real files in the checkout
     const target = resolve(repoRoot, repoRel); // where the app globs them
-    const isDir = map.kind !== "file";
 
-    if (!existsSync(source)) {
-      console.warn(`  ⚠ checkout has no ${wsRel} — skipping (${map.kind ?? "?"})`);
-      continue;
-    }
+    if (!existsSync(source)) return false;
 
     // Ensure the destination's parent exists (e.g. content/ or themes/tenants/).
     mkdirSync(dirname(target), { recursive: true });
@@ -322,9 +317,31 @@ if (workspacePath) {
     }
 
     console.log(`  ↪ ${repoRel} ⇐ ${wsRel}${backup ? " (in-tree content backed up)" : ""}`);
+    return true;
   }
 
-  if (grafts.length === 0) {
+  // `workspace` is the checkout-relative prefix (e.g. "content/", "theme.json").
+  // COLOCATION: a tenant IS the repo-root dir `tenants/<id>/`, and the checkout
+  // (a `git subtree split --prefix=tenants/<id>` of that dir) has the SAME layout
+  // at its root — so the graft is an identity map: content/ -> tenants/<id>/content/,
+  // public/ -> tenants/<id>/public/, theme.json -> tenants/<id>/theme.json. We map
+  // structurally (ignoring any legacy `repo` field in the checkout's .tot/config.json).
+  // standaloneGraftPlan ALSO appends `.tot/config.json` unconditionally — see its
+  // own doc comment. Its success does NOT count toward "did we graft a usable
+  // site" below: a checkout with config but no content/public/theme is still
+  // nothing to serve.
+  let mappedCount = 0;
+  for (const { workspace, isDir } of standaloneGraftPlan(mappings)) {
+    const grafted = graftOne(workspace, isDir);
+    if (workspace === ".tot/config.json") {
+      if (!grafted) console.warn(`  ⚠ checkout has no .tot/config.json — compliance/capabilities/siteType resolve undeclared.`);
+      continue;
+    }
+    if (grafted) mappedCount++;
+    else console.warn(`  ⚠ checkout has no ${workspace} — skipping`);
+  }
+
+  if (mappedCount === 0) {
     console.error(`✗ nothing to graft — the checkout had none of the mapped prefixes.`);
     cleanupGrafts();
     process.exit(1);
@@ -354,12 +371,19 @@ if (workspacePath) {
 // which then mismatches the URL we (and the CLI's liveness poll) advertise.
 // Instead we pick the first free port ourselves and PRINT it, so a busy default
 // port "just works" (better UX than failing). See port-check.mjs.
+//
+// BEFORE drifting, classify WHY the requested port is busy (port-lock.mjs). When
+// an earlier `tot dev` session holds it — still running but possibly wedged after
+// a renderer crash, or exited with the socket lingering — the developer's browser
+// tab on that port is NOT this session, so say so and name the process to stop.
 const requestedPort = Number(flag("port", "4321"));
+const busy = await classifyBusyPort(requestedPort, { isFree: isPortFree });
 const resolvedPort = await firstFreePort(requestedPort);
 const port = String(resolvedPort);
 if (resolvedPort !== requestedPort) {
-  console.log(`  ⚠ port ${requestedPort} was busy — starting on ${resolvedPort} instead.`);
+  console.log(busyPortMessage(requestedPort, resolvedPort, busy));
 }
+lockPort(resolvedPort);
 
 // Land the developer on their store ROOT (plain save→reload HMR against their own
 // site) — not the /dev cockpit, which is a hosted-only surface excluded from the
@@ -429,15 +453,20 @@ const child = spawn(
   { cwd: appDir, stdio: "inherit", env: spawnEnv },
 );
 
-// Clean up grafts on every exit path so we never leave symlinks in the tree.
+// Clean up grafts + the port lock on every exit path so we never leave
+// symlinks in the tree, or a lock a LATER run would misread as still live.
 function shutdown(signal) {
   child.kill(signal);
 }
-child.on("exit", (code) => {
+function cleanupAll() {
   cleanupGrafts();
+  unlockPort(resolvedPort);
+}
+child.on("exit", (code) => {
+  cleanupAll();
   process.exit(code ?? 0);
 });
 process.on("SIGINT", () => shutdown("SIGINT"));
 process.on("SIGTERM", () => shutdown("SIGTERM"));
 // Belt-and-suspenders: if the parent dies without the child exit firing.
-process.on("exit", cleanupGrafts);
+process.on("exit", cleanupAll);