@officexapp/vidfarm-devcli 0.21.12 → 0.21.14

package/.agents/skills/vidfarm-director/references/automation-and-local-dev.md

@@ -173,7 +173,7 @@ If a local AI script rewrites text or scenes without consuming those files first
 | `vidfarm raws preset list\|run\|save` / `raws export <ids…> --to <dir>` | (local library) | saved queries; copy raw MP4s out |
 | `vidfarm lint <dir\|composition.html>` | (local static validation) | pre-publish composition check: timing, overlaps, preset names, media src |
 | `vidfarm stills <dir> [--at 0,2.5,…]` | (local in-process render of PNG frames) | visually verify an edit without a full render |
-| `vidfarm doctor` | (local environment triage) | check ffmpeg/node/keys/agent CLI/poisoned env before debugging anything else |
+| `vidfarm doctor` | (local environment triage) | check ffmpeg/node/keys/agent CLI/poisoned env + list local serve/preview processes before debugging anything else; `--kill-orphans` reaps dead servers squatting ports (fixes the "Waiting for preview server…" hang) |
 | `vidfarm skills list\|add <name>\|update` | `GET /skill-pack/index.json` · `/skill-pack/:name/*` | install/refresh skill packs (see "Skill packs — import on demand") |
 | `vidfarm tts "…" --engine local` / `vidfarm stt <file> --engine whisper` | (keyless LOCAL engines: Kokoro-82M TTS, whisper.cpp STT) | narration + word-timestamp transcripts with zero keys and zero accounts |
 | `vidfarm remove-background <video\|image>` | (local ONNX matting — free) | transparent-subject media for occlusion captions/cutouts (arbitrary/messy background; for a FLAT solid background use `remove-background-greenscreen`) |
@@ -220,7 +220,24 @@ How the loop works:
 
 Seeding from the cloud: `serve <template_id>` pulls the template's **default fork** (which may be another user's public decomposition); `serve --fork <id>` pulls a specific fork. Only the composition + records are localized — media stays on cloud URLs. Re-serving keeps local edits unless you pass `--refetch`.
 
-Flags: `--port` (default 3000), `--dir` (default `./.vidfarm-local`), `--key` (bootstrap/browser key, or `VIDFARM_API_KEY`), `--fork <id>`, `--host` (cloud host to mirror + pull from, default `https://vidfarm.cc`), `--api-key` (cloud key for pulls, `/library`, and cloud render — defaults to `VIDFARM_API_KEY`), `--refetch`, `--no-cloud` (fully offline: no cloud catalog, seeding, or cloud render), `--no-open`. `vidfarm <template_id>` is an alias for `serve <template_id>`.
+Flags: `--port` (default 3000; **auto-advances to the next free port** so a second/third job never collides), `--dir` (default `./.vidfarm-local`), `--key` (bootstrap/browser key, or `VIDFARM_API_KEY`), `--fork <id>`, `--host` (cloud host to mirror + pull from, default `https://vidfarm.cc`), `--api-key` (cloud key for pulls, `/library`, and cloud render — defaults to `VIDFARM_API_KEY`), `--refetch`, `--no-cloud` (fully offline: no cloud catalog, seeding, or cloud render), `--no-open`. `vidfarm <template_id>` is an alias for `serve <template_id>`.
+
+### Running several local jobs at once (and cleaning up orphans)
+
+Customers routinely run more than one local video job in parallel — one `vidfarm serve` per fork. This is safe and expected:
+
+- **Ports auto-resolve.** `serve` claims the next free port at or above `--port`, so the 1st box lands on `3000`, the 2nd on `3001`, and so on. It prints `using <port> instead` when it moves, and never crashes with `EADDRINUSE`. To pin a specific port, pass `--port <n>`; if that exact port is taken it still advances (with a warning) rather than failing.
+- **Give each job its own data dir.** Concurrent boxes editing the *same* fork should not share a `--dir`, or their disk edits race. Use a distinct `--dir ./work-<n>` per job: `vidfarm serve <tpl> --fork <fork> --port 3000 --dir ./job-a` alongside `... --port 3001 --dir ./job-b`. Different forks under **one** server co-edit fine (the loop suppresses self-writes); it's the *same fork in two servers* that collides.
+- **Reference the printed URL, not `localhost:3000`.** When a box moves to `3001`, its media and reference URLs are only valid on *that* origin — pass `--base-url http://localhost:<port>` to `place` for off-disk media (see "Local file paths as media").
+
+**Orphaned servers.** If the devcli is upgraded, renamed, or its package dir is pruned while a `serve` / `hyperframes preview` is still running, that process keeps holding its port but now runs from a **deleted path** — it serves broken assets forever. This is the classic `/editor` **"Waiting for preview server… run npm run dev"** hang: the preview backend is a dead orphan. Diagnose and reclaim:
+
+```bash
+vidfarm doctor                 # the "local servers" line lists every serve/preview + flags ⚠ORPHAN (binary deleted)
+vidfarm doctor --kill-orphans  # SIGTERM (then SIGKILL) every orphaned server and free its port
+```
+
+`--kill-orphans` only reaps processes whose launch script no longer exists on disk (never a live, healthy server, never the current process). After reaping, re-launch `serve` from the current install. If a *healthy* server is holding the port you want, just let `serve` pick the next free one (or stop that job first).
 
 To *analyze* the source media locally (videos, transcript, recurring cast), read the `video-context.json` / `cast.json` routes, or pull a media URL with `vidfarm download <url>`.
 

package/SKILL.director.md

@@ -1158,7 +1158,7 @@ If a local AI script rewrites text or scenes without consuming those files first
 | `vidfarm raws preset list\|run\|save` / `raws export <ids…> --to <dir>` | (local library) | saved queries; copy raw MP4s out |
 | `vidfarm lint <dir\|composition.html>` | (local static validation) | pre-publish composition check: timing, overlaps, preset names, media src |
 | `vidfarm stills <dir> [--at 0,2.5,…]` | (local in-process render of PNG frames) | visually verify an edit without a full render |
-| `vidfarm doctor` | (local environment triage) | check ffmpeg/node/keys/agent CLI/poisoned env before debugging anything else |
+| `vidfarm doctor` | (local environment triage) | check ffmpeg/node/keys/agent CLI/poisoned env + list local serve/preview processes before debugging anything else; `--kill-orphans` reaps dead servers squatting ports (fixes the "Waiting for preview server…" hang) |
 | `vidfarm skills list\|add <name>\|update` | `GET /skill-pack/index.json` · `/skill-pack/:name/*` | install/refresh skill packs (see "Skill packs — import on demand") |
 | `vidfarm tts "…" --engine local` / `vidfarm stt <file> --engine whisper` | (keyless LOCAL engines: Kokoro-82M TTS, whisper.cpp STT) | narration + word-timestamp transcripts with zero keys and zero accounts |
 | `vidfarm remove-background <video\|image>` | (local ONNX matting — free) | transparent-subject media for occlusion captions/cutouts (arbitrary/messy background; for a FLAT solid background use `remove-background-greenscreen`) |
@@ -1205,7 +1205,24 @@ How the loop works:
 
 Seeding from the cloud: `serve <template_id>` pulls the template's **default fork** (which may be another user's public decomposition); `serve --fork <id>` pulls a specific fork. Only the composition + records are localized — media stays on cloud URLs. Re-serving keeps local edits unless you pass `--refetch`.
 
-Flags: `--port` (default 3000), `--dir` (default `./.vidfarm-local`), `--key` (bootstrap/browser key, or `VIDFARM_API_KEY`), `--fork <id>`, `--host` (cloud host to mirror + pull from, default `https://vidfarm.cc`), `--api-key` (cloud key for pulls, `/library`, and cloud render — defaults to `VIDFARM_API_KEY`), `--refetch`, `--no-cloud` (fully offline: no cloud catalog, seeding, or cloud render), `--no-open`. `vidfarm <template_id>` is an alias for `serve <template_id>`.
+Flags: `--port` (default 3000; **auto-advances to the next free port** so a second/third job never collides), `--dir` (default `./.vidfarm-local`), `--key` (bootstrap/browser key, or `VIDFARM_API_KEY`), `--fork <id>`, `--host` (cloud host to mirror + pull from, default `https://vidfarm.cc`), `--api-key` (cloud key for pulls, `/library`, and cloud render — defaults to `VIDFARM_API_KEY`), `--refetch`, `--no-cloud` (fully offline: no cloud catalog, seeding, or cloud render), `--no-open`. `vidfarm <template_id>` is an alias for `serve <template_id>`.
+
+### Running several local jobs at once (and cleaning up orphans)
+
+Customers routinely run more than one local video job in parallel — one `vidfarm serve` per fork. This is safe and expected:
+
+- **Ports auto-resolve.** `serve` claims the next free port at or above `--port`, so the 1st box lands on `3000`, the 2nd on `3001`, and so on. It prints `using <port> instead` when it moves, and never crashes with `EADDRINUSE`. To pin a specific port, pass `--port <n>`; if that exact port is taken it still advances (with a warning) rather than failing.
+- **Give each job its own data dir.** Concurrent boxes editing the *same* fork should not share a `--dir`, or their disk edits race. Use a distinct `--dir ./work-<n>` per job: `vidfarm serve <tpl> --fork <fork> --port 3000 --dir ./job-a` alongside `... --port 3001 --dir ./job-b`. Different forks under **one** server co-edit fine (the loop suppresses self-writes); it's the *same fork in two servers* that collides.
+- **Reference the printed URL, not `localhost:3000`.** When a box moves to `3001`, its media and reference URLs are only valid on *that* origin — pass `--base-url http://localhost:<port>` to `place` for off-disk media (see "Local file paths as media").
+
+**Orphaned servers.** If the devcli is upgraded, renamed, or its package dir is pruned while a `serve` / `hyperframes preview` is still running, that process keeps holding its port but now runs from a **deleted path** — it serves broken assets forever. This is the classic `/editor` **"Waiting for preview server… run npm run dev"** hang: the preview backend is a dead orphan. Diagnose and reclaim:
+
+```bash
+vidfarm doctor                 # the "local servers" line lists every serve/preview + flags ⚠ORPHAN (binary deleted)
+vidfarm doctor --kill-orphans  # SIGTERM (then SIGKILL) every orphaned server and free its port
+```
+
+`--kill-orphans` only reaps processes whose launch script no longer exists on disk (never a live, healthy server, never the current process). After reaping, re-launch `serve` from the current install. If a *healthy* server is holding the port you want, just let `serve` pick the next free one (or stop that job first).
 
 To *analyze* the source media locally (videos, transcript, recurring cast), read the `video-context.json` / `cast.json` routes, or pull a media URL with `vidfarm download <url>`.