tina4-nodejs 3.13.98 → 3.13.99

package/packages/core/src/mcp.ts

@@ -20,6 +20,7 @@ import * as os from "node:os";
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
 import { randomBytes } from "node:crypto";
+import { TINA4_VERSION } from "./version.js";
 
 // Synchronous CommonJS-style require that works under real ESM (where the
 // bare `require` global is undefined). Dev-tool handlers are synchronous, so
@@ -728,7 +729,14 @@ let _defaultToolsRegistered = false;
 
 function _getDefaultServer(): McpServer {
   if (_defaultServer === null) {
-    _defaultServer = new McpServer("/__dev/mcp", "Tina4 Dev Tools");
+    // VERSION-DEC-01 (feature 130): the built-in dev server's serverInfo must
+    // report the SAME version every other surface does, not the constructor's
+    // generic '1.0.0' default -- TINA4_VERSION is the one shared resolver
+    // (health, banner, dashboard already read it). A user's OWN custom
+    // `new McpServer(path, name)` (no third arg) is unaffected -- that default
+    // stays '1.0.0' for app authors who have not set their own tool-server
+    // version.
+    _defaultServer = new McpServer("/__dev/mcp", "Tina4 Dev Tools", TINA4_VERSION);
   }
   return _defaultServer;
 }

package/packages/core/src/messenger.ts

@@ -43,6 +43,17 @@ function tlsRejectUnauthorized(): boolean {
   return !isTruthy(process.env.TINA4_MAIL_TLS_INSECURE);
 }
 
+/**
+ * Parse TINA4_MAIL_REDIRECT_TO (MAIL-DEC-01): comma-separated addresses, each
+ * trimmed, blanks dropped. Unset/empty -> [] (redirect off, no behaviour
+ * change). Read fresh on every send() call — same style as shouldCapture()'s
+ * TINA4_MAIL_CAPTURE read — so a changed env is honoured without restart.
+ */
+function parseMailRedirectList(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
 // ── Types ────────────────────────────────────────────────────
 
 export interface SendResult {
@@ -476,10 +487,10 @@ export class Messenger {
     headers?: Record<string, string>,
   ): Promise<SendResult> {
     const options: SendOptions = { to, subject, body, html, text, cc, bcc, replyTo, attachments, headers };
-    const toList = Array.isArray(options.to) ? options.to : [options.to];
-    const ccList = Array.isArray(options.cc) ? options.cc : (options.cc ? [options.cc] : []);
-    const bccList = Array.isArray(options.bcc) ? options.bcc : (options.bcc ? [options.bcc] : []);
-    const allRecipients = [...toList, ...ccList, ...bccList];
+    let toList = Array.isArray(options.to) ? options.to : [options.to];
+    let ccList = Array.isArray(options.cc) ? options.cc : (options.cc ? [options.cc] : []);
+    let bccList = Array.isArray(options.bcc) ? options.bcc : (options.bcc ? [options.bcc] : []);
+    let allRecipients = [...toList, ...ccList, ...bccList];
 
     // Dev capture is a BRANCH here, not a different object returned by the factory.
     // createMessenger() used to hand back a DevMailbox, which has capture() and no
@@ -491,6 +502,22 @@ export class Messenger {
       );
     }
 
+    // TINA4_MAIL_REDIRECT_TO (MAIL-DEC-01): on the REAL-SEND path only — capture
+    // already returned above, so this never touches the capture branch. When the
+    // list is non-empty, replace every recipient with the redirect list (so ONLY
+    // the dev list receives the mail, never the real recipients) and preserve the
+    // original recipients in X-Tina4-Original-To. Subject/body/attachments are
+    // untouched, and send()'s return shape is unchanged.
+    const redirectTo = parseMailRedirectList(process.env.TINA4_MAIL_REDIRECT_TO);
+    if (redirectTo.length > 0) {
+      const originalTo = allRecipients.join(", ");
+      toList = redirectTo;
+      ccList = [];
+      bccList = [];
+      allRecipients = [...toList];
+      options.headers = { ...(options.headers ?? {}), "X-Tina4-Original-To": originalTo };
+    }
+
     const messageId = `${randomUUID()}@${this.host}`;
 
     if (allRecipients.length === 0) {

package/packages/core/src/middleware.ts

@@ -5,6 +5,7 @@ import { Log } from "./logger.js";
 import { isTruthy } from "./dotenv.js";
 import { defaultRouter, type Router } from "./router.js";
 import { resolveClientIp } from "./trustedProxy.js";
+import { getFrond, getFrameworkFrond, wantsJson, negotiatedErrorBody } from "./response.js";
 
 /**
  * Whether to emit a per-request log line (v3.13.14). TINA4_LOG_REQUESTS is
@@ -101,6 +102,55 @@ function isResponse(value: unknown): value is Tina4Response {
     && typeof (value as Tina4Response).raw?.end === "function";
 }
 
+/**
+ * The 403 a hook gets when it says no without saying what to send
+ * (ERR-DEC-01/ERR-DEC-02). Routed through the SAME negotiated renderer
+ * 404/500 use (server.ts's serveNotFound/renderDispatchError share the same
+ * getFrond/getFrameworkFrond singletons via response.ts), so a middleware
+ * refusal looks like every other error page - a user template if the app
+ * ships one, the framework's errors/403.twig otherwise, negotiated JSON for
+ * an API client - instead of the old bare `res.raw.statusCode = 403` with no
+ * body at all.
+ */
+async function renderForbidden(req: Tina4Request, res: Tina4Response): Promise<void> {
+  const requestId = Log.getRequestId() ?? "";
+
+  if (wantsJson(req)) {
+    const body = negotiatedErrorBody(403, "Forbidden", requestId);
+    res.raw.statusCode = HTTP_FORBIDDEN;
+    res.raw.setHeader("Content-Type", "application/json");
+    res.raw.end(JSON.stringify(body));
+    return;
+  }
+
+  const data = { path: req.path ?? "", error_message: "Forbidden", request_id: requestId, status_code: 403 };
+  let html: string | null = null;
+  try {
+    html = (await getFrond()).render("errors/403.twig", data);
+  } catch {
+    // fall through to the framework default
+  }
+  if (!html) {
+    try {
+      const fw = await getFrameworkFrond();
+      html = fw ? fw.render("errors/403.twig", data) : null;
+    } catch {
+      html = null;
+    }
+  }
+
+  if (html) {
+    res.raw.writeHead(HTTP_FORBIDDEN, { "Content-Type": "text/html; charset=utf-8" });
+    res.raw.end(html);
+    return;
+  }
+
+  const body = negotiatedErrorBody(403, "Forbidden", requestId);
+  res.raw.statusCode = HTTP_FORBIDDEN;
+  res.raw.setHeader("Content-Type", "application/json");
+  res.raw.end(JSON.stringify(body));
+}
+
 /**
  * ONE return-value table, for EVERY beforeX/afterX hook, at EVERY scope
  * (global and per-route):
@@ -111,17 +161,19 @@ function isResponse(value: unknown): value is Tina4Response {
  *   the [req, res] pair rebind both, continue (length >= 2, mirroring Python's
  *                       `isinstance(result, tuple) and len(result) >= 2`)
  *   false               SHORT-CIRCUIT. Send the response AS SET; a still
- *                       default and still unwritten response becomes a 403,
- *                       because a bare `return false` is a deny.
+ *                       default and still unwritten response becomes a
+ *                       NEGOTIATED 403 (renderForbidden), because a bare
+ *                       `return false` is a deny.
  *   undefined / null    continue
  *
+ * ASYNC because the false-row now renders a template (await getFrond()).
  * Returns [req, res, stop].
  */
-function interpretHookResult(
+async function interpretHookResult(
   result: unknown,
   req: Tina4Request,
   res: Tina4Response,
-): [Tina4Request, Tina4Response, boolean] {
+): Promise<[Tina4Request, Tina4Response, boolean]> {
   if (Array.isArray(result)) {
     return result.length >= 2
       ? [result[0] as Tina4Request, result[1] as Tina4Response, false]
@@ -130,7 +182,7 @@ function interpretHookResult(
   if (isResponse(result)) return [req, result, true];
   if (result === false) {
     if (!res.raw.writableEnded && res.raw.statusCode === HTTP_OK) {
-      res.raw.statusCode = HTTP_FORBIDDEN;
+      await renderForbidden(req, res);
     }
     return [req, res, true];
   }
@@ -319,7 +371,7 @@ export class MiddlewareRunner {
       for (const method of MiddlewareRunner.methodNames(cls, "before")) {
         try {
           const [nextReq, nextRes, stop] =
-            interpretHookResult(await cls[method](req, res), req, res);
+            await interpretHookResult(await cls[method](req, res), req, res);
           req = nextReq;
           res = nextRes;
           if (stop) return [req, res, false];
@@ -376,7 +428,7 @@ export class MiddlewareRunner {
       for (const method of MiddlewareRunner.methodNames(cls, "after")) {
         try {
           const [nextReq, nextRes, stop] =
-            interpretHookResult(await cls[method](req, res), req, res);
+            await interpretHookResult(await cls[method](req, res), req, res);
           req = nextReq;
           res = nextRes;
           if (stop) return [req, res];
@@ -822,8 +874,13 @@ export class SecurityHeadersMiddleware {
 
     res.header("X-Content-Type-Options", "nosniff");
 
+    // HSTS is HTTPS-only (SECHDR-DEC-02): a downgrade-protection header on a
+    // plain-HTTP response is inert at best and ships a bad max-age on an
+    // unencrypted scheme at worst. Emit it ONLY when TINA4_HSTS is set AND the
+    // request is HTTPS (x-forwarded-proto first hop, else the native TLS socket)
+    // — the same proxy-aware scheme the session cookie's Secure flag uses.
     const hsts = process.env.TINA4_HSTS ?? "";
-    if (hsts) {
+    if (hsts && SecurityHeadersMiddleware.isSecureRequest(req)) {
       res.header(
         "Strict-Transport-Security",
         `max-age=${hsts}; includeSubDomains`,
@@ -849,31 +906,71 @@ export class SecurityHeadersMiddleware {
 
     return [req, res];
   }
+
+  /**
+   * True when the client request is HTTPS. Proxy-aware and byte-parity with
+   * Python (request.is_secure_scheme), PHP (Request::isSecureScheme) and Ruby
+   * (Request.secure_scheme?): a TLS-terminating proxy forwards plain HTTP with
+   * `x-forwarded-proto`, whose FIRST hop is the client-facing scheme; falling
+   * back to the native TLS socket when no such header is present. Its name is
+   * not before- or after-prefixed, so hook discovery never calls it as a hook.
+   */
+  private static isSecureRequest(req: Tina4Request): boolean {
+    const xfProto = (req.headers as Record<string, string | string[] | undefined>)[
+      "x-forwarded-proto"
+    ];
+    const firstHop = (Array.isArray(xfProto) ? xfProto[0] : xfProto)
+      ?.split(",")[0]
+      ?.trim()
+      .toLowerCase();
+    if (firstHop) return firstHop === "https";
+    return Boolean((req.socket as { encrypted?: boolean } | undefined)?.encrypted);
+  }
 }
 
 /**
  * Class-based CSRF middleware using the before/after convention.
  * Validates form tokens on state-changing requests (POST, PUT, PATCH, DELETE).
  *
- * Off by default — only active when TINA4_CSRF=true in .env or when
- * registered explicitly via Router.use(CsrfMiddleware).
+ * OFF by default — a default app has NO CSRF gate because the middleware is
+ * NOT attached. Set TINA4_CSRF=true (or 1/yes/on) and the framework
+ * auto-attaches it at boot (see attachCsrfFromEnv); or register it explicitly
+ * via Router.use(CsrfMiddleware). Once attached, TINA4_CSRF=false (or 0/no) is
+ * the kill switch that disables enforcement again.
  *
- * Behaviour:
+ * Behaviour (identical to the Python master, feature 37):
  *   - Skips GET, HEAD, OPTIONS requests.
  *   - Skips routes marked .noAuth().
+ *   - Fails CLOSED: with TINA4_SECRET unset the signing secret resolves to
+ *     blank (there is NO built-in default), and a blank HMAC key is publicly
+ *     reproducible — so no token can be trusted and every write is rejected
+ *     (403). This is the SEC-01 / CSRF-DEC-01 no-default-secret guarantee.
  *   - Skips requests with a valid Authorization: Bearer header (API clients).
  *   - Checks request body formToken then X-Form-Token header.
  *   - Rejects if token found in query string formToken (log warning, 403).
- *   - Validates token with validToken using SECRET env var.
+ *   - Validates token with validToken using the resolved SECRET, and enforces
+ *     that the token's `type` claim is "form" — a non-form JWT presented in the
+ *     formToken slot is rejected (CSRF-DEC-02).
  *   - If token payload has session_id, verifies it matches request session.
- *   - Returns 403 on failure.
+ *   - Every rejection is 403 with the CSRF_INVALID envelope
+ *     { error: true, code: "CSRF_INVALID", message, status: 403 }.
  *
  * Usage:
  *   Router.use(CsrfMiddleware);
  */
 export class CsrfMiddleware {
   static beforeCsrf(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response] {
-    // Skip CSRF validation entirely if disabled via env
+    // Every CSRF rejection carries the SAME 403 envelope across all four
+    // frameworks (Python master's shape): a real client recognises a CSRF
+    // failure by one stable code + status regardless of the framework.
+    const reject = (message: string): [Tina4Request, Tina4Response] => {
+      res({ error: true, code: "CSRF_INVALID", message, status: HTTP_FORBIDDEN }, HTTP_FORBIDDEN);
+      return [req, res];
+    };
+
+    // TINA4_CSRF=false (or 0/no) disables all CSRF checks, even when the
+    // middleware is attached — the documented kill switch. Unset defaults to
+    // enabled (the middleware only runs at all once attached).
     const csrfEnv = process.env.TINA4_CSRF;
     if (csrfEnv === "false" || csrfEnv === "0" || csrfEnv === "no") {
       return [req, res];
@@ -891,26 +988,35 @@ export class CsrfMiddleware {
       return [req, res];
     }
 
-    // Skip requests with valid Bearer token (API clients)
+    // Resolve the signing secret ONCE, fail-closed — IDENTICAL to the validator
+    // (auth.ts validToken: `secret ?? process.env.TINA4_SECRET ?? ""`). Blank
+    // when TINA4_SECRET is unset; there is NO built-in default.
+    const secret = process.env.TINA4_SECRET ?? "";
+
+    // BLANK-SECRET HARD-FAIL (SEC-01 / CSRF-DEC-01): a blank HMAC key is
+    // publicly reproducible, so a token signed with it (or with the retired
+    // public 'tina4-default-secret') is a forgery. Reject every write rather
+    // than validate against a guessable key — fail closed, hard.
+    if (secret === "") {
+      return reject("CSRF token cannot be validated: TINA4_SECRET is not set");
+    }
+
+    // Skip requests with a valid Bearer token (API clients). Pass the resolved
+    // secret so the Bearer check uses the SAME key as the form-token check.
     const authHeader = req.headers.authorization ?? "";
     if (authHeader.startsWith("Bearer ")) {
       const bearerToken = authHeader.slice(7).trim();
-      if (bearerToken) {
-        if (validToken(bearerToken)) {
-          return [req, res];
-        }
+      if (bearerToken && validToken(bearerToken, secret)) {
+        return [req, res];
       }
     }
 
-    // Reject if token is in query string (security risk)
+    // Reject if token is in query string (security risk — a URL leaks through
+    // logs, referers and history).
     const query = (req as any).query ?? {};
     if (query.formToken) {
       console.warn("[Tina4 CSRF] Token found in query string — rejected for security");
-      res({
-        error: "CSRF_INVALID",
-        message: "Form token must not be sent in the URL query string",
-      }, 403);
-      return [req, res];
+      return reject("Form token must not be sent in the URL query string");
     }
 
     // Extract token: body first, then header
@@ -925,25 +1031,25 @@ export class CsrfMiddleware {
     }
 
     if (!token) {
-      res({
-        error: "CSRF_INVALID",
-        message: "Invalid or missing form token",
-      }, 403);
-      return [req, res];
+      return reject("Invalid or missing form token");
     }
 
-    // Validate the token
-    if (!validToken(token)) {
-      res({
-        error: "CSRF_INVALID",
-        message: "Invalid or missing form token",
-      }, 403);
-      return [req, res];
+    // Validate the token signature / expiry against the resolved secret.
+    if (!validToken(token, secret)) {
+      return reject("Invalid or missing form token");
     }
 
     const payload = getPayload(token) ?? {};
 
-    // Session binding — if token has session_id, verify it matches
+    // TYPE ENFORCEMENT (CSRF-DEC-02): a valid signature is not enough. A
+    // non-form JWT (e.g. an auth/session token) must never be accepted in the
+    // formToken slot — the token's `type` claim MUST be "form".
+    if (payload.type !== "form") {
+      return reject("Invalid or missing form token");
+    }
+
+    // Session binding — if token has session_id, verify it matches the request
+    // session. A token minted for one session cannot be replayed against another.
     const tokenSessionId = payload.session_id as string | undefined;
     if (tokenSessionId) {
       const session = (req as any).session;
@@ -956,11 +1062,7 @@ export class CsrfMiddleware {
       }
 
       if (currentSessionId && tokenSessionId !== currentSessionId) {
-        res({
-          error: "CSRF_INVALID",
-          message: "Invalid or missing form token",
-        }, 403);
-        return [req, res];
+        return reject("Invalid or missing form token");
       }
     }
 
@@ -968,6 +1070,30 @@ export class CsrfMiddleware {
   }
 }
 
+/**
+ * Auto-attach CsrfMiddleware when TINA4_CSRF is enabled in the environment.
+ *
+ * CSRF is OFF by default: with TINA4_CSRF unset the middleware is never
+ * attached, so a default app has no CSRF gate. Setting TINA4_CSRF to a truthy
+ * value (true/1/yes/on, case-insensitive, trimmed) attaches it globally at boot
+ * so every state-changing route is gated — the env flag is the switch, no code
+ * change needed. Idempotent (MiddlewareRunner.use de-dupes). Returns true when
+ * the middleware is now attached.
+ *
+ * The framework calls this once during startServer (after route discovery,
+ * before listen); a false/0/no value still lets an explicit Router.use opt-in
+ * be disabled at runtime by the kill switch in beforeCsrf. Mirrors Python's
+ * attach_csrf_from_env.
+ */
+export function attachCsrfFromEnv(): boolean {
+  const value = (process.env.TINA4_CSRF ?? "").trim().toLowerCase();
+  if (value === "true" || value === "1" || value === "yes" || value === "on") {
+    MiddlewareRunner.use(CsrfMiddleware);
+    return true;
+  }
+  return false;
+}
+
 // Built-in request logger middleware.
 //
 // v3.13.14: routes through the Tina4 Log (was a bare console.log) so the

package/packages/core/src/portTakeover.ts

@@ -0,0 +1,232 @@
+/**
+ * Identity-checked port takeover, shared by the CLI and the runtime paths.
+ *
+ * `tina4 serve` reclaims a busy port so the edit-restart loop does not fail with
+ * "address already in use". The convenience has a sharp edge: "whatever is
+ * listening" is not always the old Tina4 server, and before this module BOTH
+ * takeover paths (the CLI `killProcessOnPort` and the runtime bind-failure
+ * `killPort`) SIGTERM'd whatever held the port, with NO check that the victim was
+ * a Tina4 dev server -- a foreign holder (another dev server, a database, a stray
+ * listener) was killed.
+ *
+ * This is the ONE takeover implementation both paths call (TAKEOVER-DEC-02), so
+ * the runtime path can never again be a weaker twin of the CLI path. It adds:
+ *
+ *  - Identity (TAKEOVER-DEC-01): a Tina4 dev server writes a per-port PID file
+ *    (`data/.tina4-serve-<port>.pid`) when it binds and removes it on clean exit.
+ *    Takeover only signals a holder whose PID matches that file; a holder with no
+ *    matching Tina4 PID file is REFUSED, never killed.
+ *  - Dev gate + opt-out (TAKEOVER-DEC-03): takeover runs only in dev
+ *    (`TINA4_DEBUG` truthy) and only when not opted out (`TINA4_NO_TAKEOVER` /
+ *    `tina4 serve --no-kill`). A production bind never kills a port holder.
+ *  - The existing PID safety filter and container guard, unchanged, on top.
+ *
+ * Refusing is always safe (the developer frees the port by hand); over-killing
+ * was the bug this fixes.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+export const TAKEOVER_NOTHING = "nothing";
+export const TAKEOVER_KILLED = "killed";
+export const TAKEOVER_REFUSED_FOREIGN = "refused_foreign";
+export const TAKEOVER_REFUSED_OPTOUT = "refused_optout";
+export const TAKEOVER_REFUSED_PROD = "refused_prod";
+export const TAKEOVER_SKIPPED_CONTAINER = "skipped_container";
+/** Statuses that mean a holder was left running on purpose. */
+export const TAKEOVER_REFUSALS = [
+  TAKEOVER_REFUSED_FOREIGN,
+  TAKEOVER_REFUSED_OPTOUT,
+  TAKEOVER_REFUSED_PROD,
+];
+
+export interface TakeoverResult {
+  status: string;
+  port: number;
+  killed: number[];
+  message: string;
+}
+
+function isTruthy(value: string | undefined): boolean {
+  return ["true", "1", "yes", "on"].includes(String(value ?? "").trim().toLowerCase());
+}
+
+/** Dev mode = TINA4_DEBUG truthy. Takeover runs only in dev. */
+export function isDev(): boolean {
+  return isTruthy(process.env.TINA4_DEBUG);
+}
+
+/** True when takeover is disabled via TINA4_NO_TAKEOVER. */
+export function noTakeoverOptedOut(): boolean {
+  return isTruthy(process.env.TINA4_NO_TAKEOVER);
+}
+
+/**
+ * True when this process is running inside a container. Reclaiming a port makes
+ * sense on a dev machine; inside a container the server IS the container, so
+ * there is no stale sibling to reclaim from.
+ */
+export function inContainer(): boolean {
+  if (existsSync("/.dockerenv") || existsSync("/run/.containerenv")) return true;
+  try {
+    const blob = readFileSync("/proc/1/cgroup", "utf-8");
+    return blob.includes("docker") || blob.includes("containerd") || blob.includes("kubepods");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The PIDs from `lsof -ti` output that are safe to signal.
+ *
+ * Pure so the safety rule can be tested directly. A non-numeric field parses to
+ * NaN/0, and signalling PID 0 hits EVERY process in the caller's own process
+ * group -- the server kills itself. Accept only all-digit tokens; never PID 0
+ * (our group), PID 1 (init), ourselves, or our own process group. This is the
+ * PID-SAFETY gate only; whether a survivor is a Tina4 server is the SEPARATE
+ * identity check in takeOverPort().
+ */
+export function selectablePids(lsofOutput: string, me: number, myGroup?: number): number[] {
+  const pids: number[] = [];
+  for (const token of lsofOutput.split(/\s+/)) {
+    if (!/^\d+$/.test(token)) continue; // never coerce junk into a PID
+    const pid = Number(token);
+    if (pid <= 1 || pid === me) continue; // 0 = our group, 1 = init, me = suicide
+    if (myGroup !== undefined && pid === myGroup) continue;
+    if (!pids.includes(pid)) pids.push(pid);
+  }
+  return pids;
+}
+
+export function runtimeDir(baseDir?: string): string {
+  return baseDir ?? join(process.cwd(), "data");
+}
+
+export function pidfilePath(port: number, baseDir?: string): string {
+  return join(runtimeDir(baseDir), `.tina4-serve-${port}.pid`);
+}
+
+/** Record THIS process as the Tina4 dev server on `port` (best-effort). */
+export function writePidfile(port: number, baseDir?: string, pid?: number): void {
+  try {
+    mkdirSync(runtimeDir(baseDir), { recursive: true });
+    writeFileSync(pidfilePath(port, baseDir), String(pid ?? process.pid));
+  } catch {
+    /* identity is a convenience; never let it break the server */
+  }
+}
+
+/** The PID a Tina4 dev server recorded for `port`, or null if none/garbage. */
+export function readPidfile(port: number, baseDir?: string): number | null {
+  try {
+    const token = readFileSync(pidfilePath(port, baseDir), "utf-8").trim();
+    return /^\d+$/.test(token) ? Number(token) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Drop the PID file for `port` (clean shutdown, or after reclaiming it). */
+export function removePidfile(port: number, baseDir?: string): void {
+  try {
+    unlinkSync(pidfilePath(port, baseDir));
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Raw lsof/netstat PID tokens for whatever holds `port`. */
+function portHolders(port: number): string[] {
+  if (process.platform === "win32") {
+    try {
+      const out = execFileSync("netstat", ["-ano"], { encoding: "utf-8", timeout: 5000 });
+      const tokens: string[] = [];
+      for (const line of out.split("\n")) {
+        if (line.includes(`:${port}`) && (line.includes("LISTENING") || line.includes("ESTABLISHED"))) {
+          const parts = line.trim().split(/\s+/);
+          const last = parts[parts.length - 1];
+          if (/^\d+$/.test(last)) tokens.push(last);
+        }
+      }
+      return tokens;
+    } catch {
+      return [];
+    }
+  }
+  try {
+    return execFileSync("lsof", ["-ti", `:${port}`], { encoding: "utf-8", timeout: 5000 })
+      .split(/\s+/)
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/** A real synchronous pause, so the OS can reclaim the port -- no subprocess. */
+function sleepSync(ms: number): void {
+  if (ms <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Reclaim `port` ONLY from an identity-confirmed Tina4 dev server. The single
+ * guarded path for both the CLI (`tina4 serve`) and the runtime bind-failure
+ * fallback. `dev`/`noTakeover` are passed in so this stays pure and directly
+ * testable; callers resolve them from isDev() / noTakeoverOptedOut().
+ */
+export function takeOverPort(
+  port: number,
+  dev: boolean,
+  noTakeover: boolean,
+  baseDir?: string,
+  grace = 500,
+): TakeoverResult {
+  const make = (status: string, killed: number[] = [], message = ""): TakeoverResult => ({
+    status,
+    port,
+    killed,
+    message,
+  });
+
+  if (noTakeover) {
+    return make(TAKEOVER_REFUSED_OPTOUT, [],
+      `Port ${port} is in use and takeover is disabled (TINA4_NO_TAKEOVER/--no-kill) `
+      + `-- free it or choose another port.`);
+  }
+  if (!dev) {
+    return make(TAKEOVER_REFUSED_PROD, [],
+      `Port ${port} is in use; takeover is disabled outside dev mode `
+      + `-- free it or choose another port.`);
+  }
+  if (inContainer()) return make(TAKEOVER_SKIPPED_CONTAINER);
+
+  const tokens = portHolders(port);
+  if (tokens.length === 0) return make(TAKEOVER_NOTHING);
+
+  const holders = selectablePids(tokens.join(" "), process.pid);
+  if (holders.length === 0) return make(TAKEOVER_NOTHING);
+
+  const recorded = readPidfile(port, baseDir);
+  const tina4Holders = recorded === null ? [] : holders.filter((pid) => pid === recorded);
+  if (tina4Holders.length === 0) {
+    return make(TAKEOVER_REFUSED_FOREIGN, [],
+      `Port ${port} is held by a non-Tina4 process -- free it or choose another port.`);
+  }
+
+  const killed: number[] = [];
+  for (const pid of tina4Holders) {
+    try {
+      process.kill(pid, "SIGTERM");
+      killed.push(pid);
+    } catch {
+      /* already gone or no permission */
+    }
+  }
+  if (killed.length === 0) return make(TAKEOVER_NOTHING);
+
+  removePidfile(port, baseDir);
+  sleepSync(grace);
+  return make(TAKEOVER_KILLED, killed,
+    `Reclaimed port ${port} from Tina4 dev server (PID: ${killed.join(", ")}).`);
+}