@officexapp/vidfarm-devcli 0.21.12 → 0.21.14

package/dist/src/cli.js

@@ -20,6 +20,8 @@ import { resolveFfmpeg } from "./services/clip-curation/ffmpeg.js";
 import { parseHyperframesJson, runHyperframesCommand } from "./devcli/hyperframes-cli.js";
 import { renderCompositionStills } from "./devcli/stills.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
+import { findFreePort } from "./devcli/port-utils.js";
+import { scanLocalServers } from "./devcli/process-scan.js";
 import { runSkillsCommand } from "./devcli/skills.js";
 import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
 import { resolveLocalDataDir, localBackendAvailable, LocalModeUnavailableError, localApiRequest } from "./devcli/local-backend.js";
@@ -91,7 +93,8 @@ Local editor loop:
                               With a template_id or --fork, pulls that composition
                               (or the template's default/shared decomposition) from
                               the cloud host onto local disk to edit offline.
-    --port <n>                Server port (default: 3000)
+    --port <n>                Server port (default: 3000; auto-advances to the next
+                              free port so concurrent local jobs never collide)
     --dir <path>              Local data dir (default: ~/.vidfarm/data or VIDFARM_HOME/data)
     --key <api-key>           Bootstrap/browser key (default: VIDFARM_API_KEY or a dev key)
     --fork <id>               Pull + open a specific cloud fork
@@ -489,7 +492,11 @@ Local media engines & toolchain (all local, free, no account — no cloud key ne
   doctor                    Health-check the local toolchain: node,       (local)
                             ffmpeg, hyperframes engines, Chrome, API key
                             (whoami), provider keys, agent CLI, poisoned
-                            env, port 3000, installed skills [--json]
+                            env, local serve/preview processes, installed
+                            skills [--json] [--kill-orphans]
+    --kill-orphans           Reap orphaned local serve/preview servers
+                            (running from a deleted package path) so their
+                            squatted ports are reclaimed
   skills <list|add <names…>|update>   Install/refresh agent skills into   → GET /skill-pack/* (or the
                             <root>/.agents/skills/<name> + a relative      copies bundled in this repo)
                             .claude/skills symlink; skills-lock.json is
@@ -649,7 +656,7 @@ Common options (any command):
   --json              Print only the raw JSON response (agent-friendly)
 
 Serve-mode options:
-  --port <n>          Local server port (default: 3000)
+  --port <n>          Local server port (default: 3000; auto-advances to the next free port)
   --dir <path>        Local data dir for disk records + storage (default: ./.vidfarm-local)
   --key <api-key>     Bootstrap/browser key (default: VIDFARM_API_KEY or a dev key)
   --fork <id>         Open a specific fork (multiple forks editable at once)
@@ -1330,10 +1337,29 @@ async function runFrontendServeCommand(argv) {
             "no-open": { type: "boolean", default: false }
         }
     });
-    const port = Number(parsed.values.port);
-    if (!Number.isFinite(port) || port <= 0) {
+    const requestedPort = Number(parsed.values.port);
+    if (!Number.isFinite(requestedPort) || requestedPort <= 0) {
         throw new Error(`Invalid --port: ${parsed.values.port}`);
     }
+    // Multiple concurrent local serves must coexist — auto-advance to the next
+    // free port instead of crashing the 2nd job with EADDRINUSE.
+    const port = await findFreePort(requestedPort);
+    if (port !== requestedPort) {
+        let squatterNote = "";
+        try {
+            const holder = scanLocalServers().servers.find((s) => s.port === requestedPort && !s.isSelf);
+            if (holder?.orphaned) {
+                squatterNote = ` (orphaned ${holder.kind} pid ${holder.pid} squatting it — \`vidfarm doctor --kill-orphans\` reclaims it)`;
+            }
+            else if (holder) {
+                squatterNote = ` (held by a running ${holder.kind}, pid ${holder.pid})`;
+            }
+        }
+        catch {
+            // advisory only
+        }
+        console.warn(`[vidfarm] serve: port ${requestedPort} busy${squatterNote}; using ${port} instead.`);
+    }
     const stored = readStoredAuth();
     const host = trimTrailingSlash(String(parsed.values.host ?? stored?.host ?? DEFAULT_HOST));
     // Only reuse the persisted key when it was minted for this host.
@@ -1405,10 +1431,33 @@ async function runServeCommand(argv) {
             "no-cloud": { type: "boolean", default: false }
         }
     });
-    const port = Number(parsed.values.port);
-    if (!Number.isFinite(port) || port <= 0) {
+    const requestedPort = Number(parsed.values.port);
+    if (!Number.isFinite(requestedPort) || requestedPort <= 0) {
         throw new Error(`Invalid --port: ${parsed.values.port}`);
     }
+    // Customers run several local video jobs at once, so never hard-fail on a
+    // busy port: claim the next free one upward from the request. This makes the
+    // 2nd/3rd `vidfarm serve` "just work" instead of crashing with EADDRINUSE.
+    const port = await findFreePort(requestedPort);
+    if (port !== requestedPort) {
+        // If an ORPHANED serve/preview (running from a deleted package path) is
+        // squatting the requested port, say so — that dead process will never free
+        // it on its own, and `vidfarm doctor --kill-orphans` reclaims it.
+        let squatterNote = "";
+        try {
+            const holder = scanLocalServers().servers.find((s) => s.port === requestedPort && !s.isSelf);
+            if (holder?.orphaned) {
+                squatterNote = ` (an orphaned ${holder.kind} pid ${holder.pid} is squatting it — reclaim with \`vidfarm doctor --kill-orphans\`)`;
+            }
+            else if (holder) {
+                squatterNote = ` (held by a running ${holder.kind}, pid ${holder.pid})`;
+            }
+        }
+        catch {
+            // advisory only
+        }
+        console.warn(`[vidfarm] serve: port ${requestedPort} busy${squatterNote}; using ${port} instead.`);
+    }
     const dataDir = parsed.values.dir
         ? path.resolve(process.cwd(), parsed.values.dir)
         : resolveLocalDataDir();

package/dist/src/devcli/composition-edit.js

@@ -16,8 +16,35 @@ const TRANSITION_PRESET_SET = new Set(TRANSITION_PRESETS);
 const TRANSITION_OUT_PRESET_SET = new Set(TRANSITION_OUT_PRESETS);
 const round3 = (v) => Number(v.toFixed(3));
 const clampPercent = (v) => Math.min(100, Math.max(0, v));
+// Matches an open tag and captures its attribute blob / self-close slash.
+// KEEP IN SYNC with OPEN_TAG_RE in src/services/composition-sanitize.ts.
+const OPEN_TAG_RE = /<([a-zA-Z][a-zA-Z0-9-]*)((?:\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'`=<>]+))?)*)\s*(\/?)>/g;
+// Quoted attribute values only — the capture keeps the quote character.
+// KEEP IN SYNC with QUOTED_ATTR_RE in src/services/composition-sanitize.ts.
+const QUOTED_ATTR_RE = /(\s+[^\s"'>/=]+\s*=\s*)("[^"]*"|'[^']*')/g;
+// Re-escape raw ">" inside quoted attribute values as "&gt;". Legal HTML, but
+// DOM serializers (linkedom here, browser outerHTML in the web editor) emit
+// the raw form, and the sealed StudioApp's string-offset source editor treats
+// the FIRST ">" as the end of an open tag — which once spliced an imported
+// layer into the middle of a root's data-viral-dna JSON. Idempotent.
+// KEEP IN SYNC with escapeGtInAttributeValues in
+// src/services/composition-sanitize.ts (backend) and
+// demo/src/vidfarm-composition-edit.ts (client twin).
+function escapeGtInAttributeValues(html) {
+    if (!html || !html.includes(">"))
+        return html;
+    return html.replace(OPEN_TAG_RE, (match, tag, rawAttrs, selfClose) => {
+        if (!rawAttrs || rawAttrs.indexOf(">") < 0)
+            return match;
+        const fixed = rawAttrs.replace(QUOTED_ATTR_RE, (_m, lead, quoted) => {
+            const q = quoted[0];
+            return lead + q + quoted.slice(1, -1).replace(/>/g, "&gt;") + q;
+        });
+        return `<${tag}${fixed}${selfClose ? "/" : ""}>`;
+    });
+}
 function serialize(document) {
-    return `<!doctype html>\n${document.documentElement.outerHTML}`;
+    return escapeGtInAttributeValues(`<!doctype html>\n${document.documentElement.outerHTML}`);
 }
 function reduceAspectRatio(width, height) {
     if (!width || !height || width <= 0 || height <= 0)
@@ -148,10 +175,45 @@ function resolveLayerNode(root, key) {
     if (!trimmed)
         return null;
     const escaped = trimmed.replace(/["\\]/g, "\\$&");
-    return root.querySelector(`[data-hf-id="${escaped}"]`)
-        ?? root.querySelector(`[data-hf-slug="${escaped}"]`)
-        ?? root.querySelector(`#${escaped.replace(/[^\w-]/g, "")}`)
-        ?? null;
+    const byAttr = root.querySelector(`[data-hf-id="${escaped}"]`)
+        ?? root.querySelector(`[data-hf-slug="${escaped}"]`);
+    if (byAttr)
+        return byAttr;
+    // id fallback via an attribute selector — a `#…` selector would throw a
+    // querySelector SyntaxError when the sanitized key ends up empty/invalid
+    // (e.g. an all-symbol key producing bare "#").
+    const idSafe = trimmed.replace(/[^\w-]/g, "");
+    return idSafe ? (root.querySelector(`[id="${idSafe}"]`) ?? null) : null;
+}
+// A miss should teach, not stonewall: name the layer keys that DO exist so an
+// agent can self-correct in one round trip (mirrors the web editLayerByKey).
+function layerNotFoundError(root, key) {
+    const available = collectClips(root).map((node) => {
+        const id = node.getAttribute?.("data-hf-id") || node.id || "";
+        const slug = node.getAttribute?.("data-hf-slug");
+        return slug && slug !== id ? `${id || slug} (slug: ${slug})` : id;
+    }).filter(Boolean);
+    const hint = available.length
+        ? ` Available layer keys: ${available.slice(0, 24).join(", ")}${available.length > 24 ? ", …" : ""}.`
+        : " The composition has no [data-start] layers.";
+    return new Error(`Layer not found: ${key}.${hint}`);
+}
+// The web editor's appendLayerHtml grows the root's data-duration whenever a
+// clip's end runs past it — mirror that after any op that can push a clip out
+// (insert/duplicate/nudge/ripple/retime/trim/set-media), so devcli edits never
+// leave clips dangling past the render window. Never shrinks.
+function extendRootDurationToCover(root) {
+    let furthest = 0;
+    for (const node of collectClips(root)) {
+        const s = numAttr(node, "data-start");
+        const d = numAttr(node, "data-duration");
+        if (Number.isFinite(s) && Number.isFinite(d))
+            furthest = Math.max(furthest, s + d);
+    }
+    const total = numAttr(root, "data-duration");
+    if (furthest > (Number.isFinite(total) ? total : 0) + 0.001) {
+        root.setAttribute("data-duration", String(round3(furthest)));
+    }
 }
 function nextAutoTrack(clips) {
     return clips.reduce((max, node) => {
@@ -283,12 +345,18 @@ export function insertMediaLayer(html, opts) {
     const clips = collectClips(root);
     const totalDuration = numAttr(root, "data-duration");
     const dur = Number.isFinite(totalDuration) ? totalDuration : 0;
-    const start = Math.max(0, dur > 0 ? Math.min(dur - 0.1, opts.start ?? 0) : (opts.start ?? 0));
-    const remaining = dur > 0 ? Math.max(0.1, dur - start) : 4;
+    // An EXPLICIT start/duration may run past the current timeline end — the
+    // root's data-duration is extended below (extendRootDurationToCover), the
+    // same way the web editor's appendLayerHtml grows the composition. Only the
+    // DEFAULTS are fitted to the existing timeline.
+    const start = Math.max(0, opts.start ?? 0);
+    const remaining = dur > start ? dur - start : 0;
     // Audio beds (narration/music/SFX) default to spanning the rest of the
     // timeline from their start; visual clips default to a 4s slot.
-    const defaultDuration = opts.kind === "audio" ? remaining : Math.min(4, remaining);
-    const duration = Math.max(0.1, dur > 0 ? Math.min(opts.duration ?? defaultDuration, remaining) : (opts.duration ?? 4));
+    const defaultDuration = opts.kind === "audio"
+        ? (remaining > 0.1 ? remaining : 4)
+        : Math.min(4, remaining > 0.1 ? remaining : 4);
+    const duration = Math.max(0.1, opts.duration ?? defaultDuration);
     const providedKey = opts.layerKey?.trim();
     const genKey = providedKey && /^[A-Za-z][\w-]{0,63}$/.test(providedKey)
         ? providedKey
@@ -305,6 +373,7 @@ export function insertMediaLayer(html, opts) {
         height: opts.height ?? 100
     });
     root.append(node);
+    extendRootDurationToCover(root);
     return { html: serialize(document), layerKey: id };
 }
 const CAPTION_DEFAULT_FRAME = { x: 10, y: 70, width: 80, height: 14 };
@@ -445,7 +514,7 @@ export function replaceLayerWithMedia(html, targetKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const target = resolveLayerNode(root, targetKey);
     if (!target)
-        throw new Error(`Layer to replace not found: ${targetKey}`);
+        throw layerNotFoundError(root, targetKey);
     const start = opts.start ?? numAttr(target, "data-start");
     const durationRaw = opts.duration ?? numAttr(target, "data-duration");
     const trackRaw = opts.track ?? numAttr(target, "data-track-index");
@@ -476,6 +545,7 @@ export function replaceLayerWithMedia(html, targetKey, opts) {
         ...geom
     });
     root.append(node);
+    extendRootDurationToCover(root);
     void targetId;
     return { html: serialize(document), layerKey: id };
 }
@@ -621,7 +691,7 @@ export function setLayerTransitions(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     if (!isSceneClipNode(node) && String(node.tagName || "").toLowerCase() === "audio") {
         throw new Error("Transitions cannot be applied to audio layers.");
     }
@@ -729,7 +799,7 @@ export function setLayerKeyframes(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const baseId = nodeTimelineId(node) || "layer";
     const animName = `hfk-${baseId.replace(/[^A-Za-z0-9_-]/g, "-")}`;
     const clipDuration = numAttr(node, "data-duration");
@@ -788,7 +858,7 @@ export function nudgeLayers(html, keys, opts) {
     for (const key of cleanKeys) {
         const seed = resolveLayerNode(root, key);
         if (!seed)
-            throw new Error(`Layer not found: ${key}`);
+            throw layerNotFoundError(root, key);
         const groupId = seed.getAttribute("data-vf-group");
         if (groupId) {
             const escaped = groupId.replace(/["\\]/g, "\\$&");
@@ -808,6 +878,7 @@ export function nudgeLayers(html, keys, opts) {
             track: Math.max(0, (Number.isFinite(track) ? track : 0) + Math.trunc(deltaTrack))
         });
     }
+    extendRootDurationToCover(root);
     return { html: serialize(document), moved: Array.from(moveSet.values()).map((n) => nodeTimelineId(n)) };
 }
 // ripple_edit twin: insert (delta > 0) or close (delta < 0) time at `at`,
@@ -830,6 +901,7 @@ export function rippleEdit(html, opts) {
         const s = numAttr(node, "data-start");
         applyTimingToNode(node, { start: Math.max(0, s + opts.delta) });
     }
+    extendRootDurationToCover(root);
     return { html: serialize(document), affected: affected.length };
 }
 // trim_layer twin: move ONE edge of a clip to a composition time. edge='start'
@@ -844,7 +916,7 @@ export function trimLayer(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const start = numAttr(node, "data-start");
     const duration = numAttr(node, "data-duration");
     const s = Number.isFinite(start) ? start : 0;
@@ -882,6 +954,7 @@ export function trimLayer(html, layerKey, opts) {
         report.duration = round3(updates.duration);
     if (updates.playbackStart !== undefined)
         report.playback_start = round3(updates.playbackStart);
+    extendRootDurationToCover(root);
     return { html: serialize(document), layerKey: nodeTimelineId(node) || layerKey, updates: report };
 }
 // set_layer_zindex twin: restack a layer. Stacking == data-track-index (higher
@@ -896,7 +969,7 @@ export function restackLayer(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const clips = collectClips(root);
     const tracks = clips.map((n) => numAttr(n, "data-track-index")).filter((t) => Number.isFinite(t));
     const currentTrack = numAttr(node, "data-track-index");
@@ -938,7 +1011,7 @@ export function setLayerText(html, layerKey, text) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const inline = node.querySelector?.("[data-vf-text-inline]");
     if (inline)
         inline.textContent = text;
@@ -955,7 +1028,7 @@ export function setLayerStyle(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const changed = [];
     if (opts.color !== undefined) {
         upsertStyleDecl(node, "color", opts.color);
@@ -1021,7 +1094,7 @@ export function setLayerVisual(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const changed = [];
     if (opts.x !== undefined) {
         upsertStyleDecl(node, "left", `${clampPercent(opts.x)}%`);
@@ -1067,7 +1140,7 @@ export function setLayerMedia(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const tag = String(node.tagName || "").toLowerCase();
     const kind = node.getAttribute("data-layer-kind") || (tag === "img" ? "image" : tag);
     if (tag !== "video" && tag !== "audio" && tag !== "img") {
@@ -1158,6 +1231,7 @@ export function setLayerMedia(html, layerKey, opts) {
     if (changed.length === 0) {
         throw new Error("set-media needs at least one of --src / --volume / --muted / --loop / --playback-start / --source-out / --duration / --object-fit / --object-position / --ken-burns / --transition / --transition-out.");
     }
+    extendRootDurationToCover(root);
     return { html: serialize(document), layerKey: nodeTimelineId(node) || layerKey, changed, kind: kind || tag };
 }
 /** Set a layer's stable slug + human note (the AI/viral-DNA handle). Pass an
@@ -1168,7 +1242,7 @@ export function setLayerIdentity(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     if (opts.slug !== undefined) {
         const slug = opts.slug.trim();
         if (slug)
@@ -1190,7 +1264,7 @@ export function duplicateLayer(html, layerKey, opts = {}) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const clips = collectClips(root);
     const start = numAttr(node, "data-start");
     const duration = numAttr(node, "data-duration");
@@ -1208,6 +1282,7 @@ export function duplicateLayer(html, layerKey, opts = {}) {
     const resolvedTrack = findNonCollidingTrack(clips, { start: newStart, duration: d, track: initialTrack }, newId);
     applyTimingToNode(clone, { start: newStart, duration: d, track: resolvedTrack });
     root.append(clone);
+    extendRootDurationToCover(root);
     return { html: serialize(document), layerKey: newId };
 }
 /** Cut a clip in two at splitTime (composition seconds). The tail inherits the
@@ -1216,7 +1291,7 @@ export function splitLayer(html, layerKey, splitTime) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const start = numAttr(node, "data-start");
     const duration = numAttr(node, "data-duration");
     const s = Number.isFinite(start) ? start : 0;
@@ -1247,7 +1322,7 @@ export function setLayerTiming(html, layerKey, opts) {
     const { document, root } = readCompositionDoc(html);
     const node = resolveLayerNode(root, layerKey);
     if (!node)
-        throw new Error(`Layer not found: ${layerKey}`);
+        throw layerNotFoundError(root, layerKey);
     const clips = collectClips(root);
     const excludeId = nodeTimelineId(node);
     const nextStart = opts.start !== undefined ? Math.max(0, opts.start) : numAttr(node, "data-start");
@@ -1260,6 +1335,7 @@ export function setLayerTiming(html, layerKey, opts) {
         track: resolvedTrack,
         playbackStart: opts.playbackStart
     });
+    extendRootDurationToCover(root);
     return { html: serialize(document), layerKey: excludeId || layerKey, track: resolvedTrack };
 }
 /** Composition-level (canvas / theme) edit: resize the frame, retarget total

package/dist/src/devcli/doctor.js

@@ -16,6 +16,8 @@ import { detectLocalAgent } from "../services/clip-curation/index.js";
 import { hasFfmpeg, resolveFfmpeg, resolveFfprobe } from "../services/clip-curation/ffmpeg.js";
 import { resolveHyperframesCli } from "./hyperframes-cli.js";
 import { resolveSkillsRoot } from "./skills.js";
+import { readStoredAuth } from "./auth-store.js";
+import { scanLocalServers, reapProcesses } from "./process-scan.js";
 const GREEN = "\x1b[32m";
 const RED = "\x1b[31m";
 const YELLOW = "\x1b[33m";
@@ -108,10 +110,14 @@ export async function runDoctorCommand(argv) {
         options: {
             host: { type: "string", default: "https://vidfarm.cc" },
             "api-key": { type: "string" },
-            json: { type: "boolean", default: false }
+            json: { type: "boolean", default: false },
+            // Reap orphaned local serve/preview processes (running from a deleted
+            // package path) so their squatted ports are reclaimed.
+            "kill-orphans": { type: "boolean", default: false }
         }
     });
     const json = Boolean(parsed.values.json);
+    const killOrphans = Boolean(parsed.values["kill-orphans"]);
     const checks = [];
     const add = (name, level, detail) => checks.push({ name, level, detail });
     // 1. Node version.
@@ -129,14 +135,21 @@ export async function runDoctorCommand(argv) {
     // 4. Chrome for the in-process render (stills / serve local render).
     const chrome = detectChromeForRender();
     add("chrome", chrome.found ? "ok" : "warn", chrome.found ? chrome.detail : `${chrome.detail} — local render/stills will try to download one on first run`);
-    // 5. Vidfarm cloud auth.
-    const apiKey = parsed.values["api-key"] ?? process.env.VIDFARM_API_KEY;
+    // 5. Vidfarm cloud auth — --api-key / env, else the persisted `vidfarm login`
+    // (auth-store), which is how most users authenticate. Without the store
+    // lookup a logged-in user got a false "VIDFARM_API_KEY not set" warning.
+    const storedAuth = readStoredAuth();
+    const explicitKey = parsed.values["api-key"] ?? process.env.VIDFARM_API_KEY;
+    const apiKey = explicitKey ?? storedAuth?.apiKey;
     if (apiKey) {
-        const who = await fetchWhoami(String(parsed.values.host).replace(/\/+$/, ""), apiKey);
-        add("vidfarm auth", who.ok ? "ok" : "warn", who.ok ? who.detail : `${who.detail} — serve will fall back to local browse mode`);
+        // A stored login was minted for its own host; only an explicit key uses --host.
+        const host = explicitKey ? String(parsed.values.host).replace(/\/+$/, "") : (storedAuth?.host ?? String(parsed.values.host)).replace(/\/+$/, "");
+        const who = await fetchWhoami(host, apiKey);
+        const source = explicitKey ? "" : " (persisted `vidfarm login`)";
+        add("vidfarm auth", who.ok ? "ok" : "warn", who.ok ? `${who.detail}${source}` : `${who.detail} — serve will fall back to local browse mode`);
     }
     else {
-        add("vidfarm auth", "warn", "VIDFARM_API_KEY not set — serve will fall back to local browse mode; cloud catalog/bulk routes need it");
+        add("vidfarm auth", "warn", "no login found — run `vidfarm login` (or set VIDFARM_API_KEY); serve will fall back to local browse mode, cloud catalog/bulk routes need it");
     }
     // 6. Provider keys in env (BYOK local-first engines).
     const presentKeys = PROVIDER_KEY_ENV_VARS.filter((name) => process.env[name]?.trim());
@@ -157,9 +170,52 @@ export async function runDoctorCommand(argv) {
     add("env cloud ARNs/URLs", poisoned.length > 0 ? "warn" : "ok", poisoned.length > 0
         ? `${poisoned.join(", ")} set — outside \`vidfarm serve\` these route local work to cloud infra (serve blanks them itself)`
         : "no stray cloud ARNs/URLs in env");
-    // 9. Port 3000 (default serve port).
-    const portBusy = await isPortInUse(3000);
-    add("port 3000", portBusy ? "warn" : "ok", portBusy ? "in use — a serve box may already be running (or pass --port to serve)" : "free");
+    // 9. Local serve/preview processes — concurrency map + orphan reaping.
+    // Customers run several local video jobs at once; a renamed/pruned devcli can
+    // also leave an orphaned server squatting a port forever (the "Waiting for
+    // preview server…" hang). List them, flag orphans, and optionally reap.
+    const scan = scanLocalServers();
+    let reapedSummary = "";
+    if (killOrphans && scan.supported) {
+        const orphans = scan.servers.filter((s) => s.orphaned && !s.isSelf);
+        if (orphans.length > 0) {
+            const results = await reapProcesses(orphans.map((s) => s.pid));
+            const killedPids = new Set(results.filter((r) => r.killed).map((r) => r.pid));
+            const survivors = results.filter((r) => !r.killed);
+            reapedSummary = `reaped ${killedPids.size}/${orphans.length} orphaned server(s): ${orphans.map((s) => `pid ${s.pid}${s.port ? `:${s.port}` : ""}`).join(", ")}`;
+            if (survivors.length > 0) {
+                reapedSummary += ` (could not kill: ${survivors.map((r) => `pid ${r.pid}${r.error ? ` — ${r.error}` : ""}`).join(", ")})`;
+            }
+            // Drop the confirmed-dead rows so the report reflects the fix.
+            scan.servers = scan.servers.filter((s) => !killedPids.has(s.pid));
+        }
+        else {
+            reapedSummary = "no orphaned servers to reap";
+        }
+    }
+    const describeServer = (s) => `${s.kind}${s.port ? ` :${s.port}` : ""} pid ${s.pid}${s.isSelf ? " (self)" : ""}${s.orphaned ? " ⚠ORPHAN (binary deleted)" : ""}`;
+    if (!scan.supported) {
+        add("local servers", "ok", scan.note ?? "scan unavailable");
+    }
+    else {
+        const others = scan.servers.filter((s) => !s.isSelf);
+        const orphanCount = others.filter((s) => s.orphaned).length;
+        // 3000 is only serve's DEFAULT start port (serve auto-advances past a busy
+        // one) — a busy 3000 is informational, and we can't be sure whose it is.
+        const portBusy = await isPortInUse(3000);
+        const port3000Note = portBusy && !others.some((s) => s.port === 3000)
+            ? "; default port 3000 is in use by another process (serve auto-advances to the next free port)"
+            : "";
+        const detail = others.length === 0
+            ? `none running${port3000Note}`
+            : `${others.length} running — ${others.map(describeServer).join("; ")}${port3000Note}`;
+        const suffix = orphanCount > 0 && !killOrphans
+            ? ` — run \`vidfarm doctor --kill-orphans\` to reclaim their ports`
+            : reapedSummary
+                ? ` — ${reapedSummary}`
+                : "";
+        add("local servers", orphanCount > 0 ? "warn" : "ok", detail + suffix);
+    }
     // 10. HeyGen credential file — vidfarm never uses it.
     const heygenCredentials = path.join(homedir(), ".heygen", "credentials");
     if (existsSync(heygenCredentials) || existsSync(path.join(homedir(), ".heygen", "credentials.json"))) {