@crievo/omni 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crievo/omni",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "OmniVideo no seu computador: o CLI omni, o studio local e as ferramentas do pipeline.",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
     "node": ">=22"
   },
   "os": [
-    "darwin"
+    "darwin",
+    "win32"
   ],
   "license": "UNLICENSED",
   "homepage": "https://omni.crievo.com",
@@ -39,6 +40,7 @@
     "voice-glow": "0.3.0",
     "zod": "4.6.5",
     "bun": "1.4.3",
-    "@puppeteer/browsers": "3.2.3"
+    "@puppeteer/browsers": "3.2.3",
+    "@napi-rs/keyring": "2.1.1"
   }
 }

package/reference/learnings.md

@@ -802,3 +802,15 @@ these voices).
 - **Symptom:** in `2026-10-18-roteiro-pronto-guia-de-motion`, c06's first frame was empty cream: the symbol that should be born at scale 0.35 on frame 0 only showed from the second frame, and the c05 → c06 cut sheet read as "ring gone, blank, symbol pops".
 - **Cause:** floating point. The build sums scene durations, so `OMNIVIDEO.start` for c06 was `16.799999999999997`, while the beat `simbolo` (from `video.scenes[].beats`) was `16.8`. A helper gated with `if (T >= t0)` (`OV.signAt`) was false at `t = 0`. Progress helpers (`seg`, clamped) don't care; only hard `>=` gates do.
 - **Fixed:** the gate takes a tolerance, `T >= t0 - 1e-4`. Rule: any on/off gate on a beat time in a continuous composition compares with an epsilon, never with a bare `>=`.
+
+## The Keychain asked for a password at every read when I swapped `security` for a library (18/10/2026)
+
+- **Symptom:** testing `@napi-rs/keyring` as the login vault on the Mac (the plan was one library for macOS, Windows and Linux), a dozen authorization dialogs opened and the reads hung: `node` reading an item `security` had written, `bun` reading an item `node` had written, and `security` reading an item `node` had written. The studio service has nobody to click them, so its token refresh would have frozen.
+- **Cause:** a Keychain item's access list names the program that created it. `security add-generic-password` makes `/usr/bin/security` the trusted reader, which is why every process (the CLI's `node`, the service's `bun`, the hook) reads the login through `security` without a prompt. Any other program, even the same library from a different binary, is a stranger to the item.
+- **Fixed:** `tools/lib/vault.mjs` keeps `security` on macOS and uses `@napi-rs/keyring` only on Windows (Credential Manager) and Linux (Secret Service), where an item belongs to the user, not to the program. Moving macOS to the library would mean every item rewritten by one binary and the studio running under that same binary, which the service and the CLI do not share. Rule: test anything that touches the Keychain with a throwaway service name, with a timeout, never the real item, and warn the user first, because every blocked read is a dialog on their screen.
+
+## `os.kill(pid, 0)` is not a probe on Windows (18/10/2026)
+
+- **Symptom:** none yet; found reading the queue for a Windows port.
+- **Cause:** on Windows, Python's `os.kill(pid, sig)` treats `sig == 0` as `CTRL_C_EVENT` and sends it to the process group of `pid`; any other number is a `TerminateProcess`. The Node `process.kill(pid, 0)` is a real probe on both systems.
+- **Fixed:** `tools/job_queue.py` asks the kernel (`OpenProcess` + `GetExitCodeProcess`, `STILL_ACTIVE`) on Windows and keeps `os.kill` plus the `ps` zombie check elsewhere. Also on Windows: `select()` works on sockets only (the guardian reads the Node pipe in a thread), an atomic replace fails while a reader has the file open (retry), and a text file is written in the code page unless `encoding="utf-8"` says otherwise.

package/reference/studio.md

@@ -300,9 +300,10 @@ studio crashes, restarts or starts in the middle of a task.
 
 1. The tool writes a ticket, `.queue/<id>.json`: tool, video, command, pid,
    origin (`chat`, `terminal`, `studio`), arrival.
-2. It waits to be the oldest live ticket waiting and then takes the `flock`
-   on `.queue/machine.lock`. The kernel releases the flock when the process
-   dies, even with `kill -9`: there is no forgotten lock.
+2. It waits to be the oldest live ticket waiting and then takes the lock
+   on `.queue/machine.lock` (`flock` on macOS and Linux, `msvcrt.locking` on
+   Windows). The kernel releases it when the process dies, even with
+   `kill -9`: there is no forgotten lock.
 3. On its turn, the tool's output goes to the terminal as always **and** to
    `.queue/<id>.log`, which the screen shows live.
 4. On exit, the ticket becomes `ok`, `error` (with the exit code) or
@@ -316,8 +317,12 @@ finished tickets are kept, with their logs.
 The protocol lives in `tools/job_queue.py` (`with turn("voice", dir):`). The
 Node tools use `tools/job-queue.mjs` (`await turn("render", dir)`), which
 runs `job_queue.py` as a guardian: a Python process that waits for the turn,
-holds the flock while the Node process lives and releases it when the stdin
-pipe closes.
+holds the lock while the Node process lives and releases it when the stdin
+pipe closes. On Windows the same protocol runs with two substitutions: the
+liveness probe asks the kernel (`GetExitCodeProcess`; `os.kill(pid, 0)` there
+would send Ctrl+C to the process group) and there is no zombie check. The
+tests (`tools/test/test_job_queue.py`, `tools/job-queue.test.mjs`) run real
+processes on all three systems.
 
 Details:
 

package/studio/api/services/queue.ts

@@ -42,6 +42,8 @@ export function isAlive(pid: number) {
   } catch (e: any) {
     if (e.code !== "EPERM") return false;
   }
+  /* Windows has no zombies, and no `ps` */
+  if (process.platform === "win32") return true;
   const ps = Bun.spawnSync(["ps", "-o", "stat=", "-p", String(pid)]);
   return !ps.stdout.toString().trim().startsWith("Z");
 }

package/studio/api/services/root.ts

@@ -3,6 +3,7 @@
 import { readFileSync, existsSync, copyFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
+import { pickPython } from "../../../tools/lib/platform.mjs";
 
 /* Two roots, as in tools/lib/paths.mjs. CODE_ROOT holds tools/, templates/, docs/ and the .venv: the
    project dir (studio/api/services → ../../..), or OMNI_CODE_ROOT when this code runs bundled into the
@@ -22,9 +23,7 @@ if (!existsSync(join(ROOT, "omnivideo.config.json")) && existsSync(join(CODE_ROO
 export const CONFIG = JSON.parse(readFileSync(join(ROOT, "omnivideo.config.json"), "utf8"));
 /* the project's Python (.venv, created by `node tools/setup.mjs`); without it, the one in the config
    (the VoiceStudio venv) and, last, the system python3 */
-export const PYTHON: string =
-  [join(CODE_ROOT, ".venv", "bin", "python"), CONFIG.voicestudio?.python ?? ""].find(p => p && existsSync(p)) ??
-  "python3";
+export const PYTHON: string = pickPython(CODE_ROOT, [CONFIG.voicestudio?.python ?? ""]);
 /* config path: relative paths are resolved from the project root */
 export const resolvePath = (p: string) => resolve(ROOT, p.replace(/^~(?=\/|$)/, homedir()));
 /* the node on PATH is the same one the chat uses; without PATH (studio opened outside a

package/studio/runner/runner.ts

@@ -114,7 +114,7 @@ export function startRunner(o: RunnerOptions) {
     /* an unreachable studio while refreshing says nothing about the login: try again later */
     const token = await Promise.resolve(o.token()).catch(() => "");
     if (!token || token === revoked) {
-      if (!hinted) log("aviso: este Mac não está pareado com o studio hospedado: node tools/runner.mjs login");
+      if (!hinted) log("aviso: este Mac não está pareado com o studio hospedado: npx -y @crievo/omni login");
       hinted = true;
       timer = setTimeout(connect, KEY_CHECK_MS);
       return;

package/studio/studio.ts

@@ -36,6 +36,7 @@ import { startRunner } from "./runner/runner";
 import { cloudSettings, env, writeEnv } from "../tools/platforms.mjs";
 import { checkKey, finishPairing, startPairing } from "../tools/lib/pairing.mjs";
 import { ACCESS_PREFIX, accessToken } from "../tools/lib/oauth-client.mjs";
+import { openUrl } from "../tools/lib/platform.mjs";
 
 const args = process.argv.slice(2);
 const option = (name: string) => {
@@ -93,7 +94,8 @@ try {
   });
 } catch (e) {
   if ((e as { code?: string })?.code === "EADDRINUSE") {
-    console.error(`erro: a porta ${PORT} já está em uso. O studio já está aberto? (lsof -i :${PORT})`);
+    const who = process.platform === "win32" ? `netstat -ano | findstr :${PORT}` : `lsof -i :${PORT}`;
+    console.error(`erro: a porta ${PORT} já está em uso. O studio já está aberto? (${who})`);
     process.exit(1);
   }
   throw e;
@@ -117,7 +119,7 @@ console.log(`OmniVideo · ${address}`);
 console.log(
   `vídeos em ${videoRoots.map(r => (relative(ROOT, r).startsWith("..") ? r : relative(ROOT, r) + "/")).join(", ")} · fila em .queue/`,
 );
-if (args.includes("--open")) Bun.spawn(["open", address]);
+if (args.includes("--open")) openUrl(address);
 
 /* --- runner ---------------------------------------------------------------------
    The hosted studio reaches this same app through the channel (docs/specs/phase-1-split-api.md).
@@ -137,7 +139,7 @@ if (args.includes("--runner") || (hosted.on && option("port") === undefined)) {
     const pair = async () => {
       const code = await startPairing(url);
       console.log(`cloud: código do pareamento ${code.user_code} · ${code.verification_uri_complete}`);
-      if (process.platform === "darwin") Bun.spawn(["open", code.verification_uri_complete]);
+      openUrl(code.verification_uri_complete);
       const paired = await finishPairing(url, code, hostname().replace(/\.local$/, ""));
       writeEnv({ OMNIVIDEO_RUNNER_TOKEN: paired.key });
       return paired.key;

package/studio/web/lib/studio-offline.ts

@@ -1,6 +1,9 @@
 /* What the "studio sem conexão" screen (components/StudioOffline.tsx) says, from what the hub knows
-   (cloud/studio/src/presence.mjs): the reason the Mac is out and the step that brings it back. A refused
-   key repairs itself (the runner opens the approval page on the Mac); the rest needs one thing on the Mac. */
+   (cloud/studio/src/presence.mjs): the reason the Mac is out and the step that brings it back. A Mac that
+   never connected gets the install (the plugin, or the CLI alone); a refused key repairs itself (the runner
+   opens the approval page on the Mac); the rest needs one thing on the Mac. The commands are the installed
+   CLI's (tools/lib/cli.mjs: `npx -y @crievo/omni …`), with the repository's own as the last step for the
+   machine that runs from a checkout. */
 
 import type { RunnerProblem } from "../types/api";
 import { formatDayTime } from "./format";
@@ -8,6 +11,10 @@ import { formatDayTime } from "./format";
 export type OfflineStep = { text: string; code?: string };
 export type OfflineAdvice = { title: string; text: string; steps: OfflineStep[] };
 
+/* the plugin's marketplace and the CLI's package (tools/lib/cli.mjs, tools/omni.mjs) */
+const PLUGIN_INSTALL = "claude plugin install omnivideo --marketplace pedroflp/omni-plugin";
+const CLI = "npx -y @crievo/omni";
+
 const theMac = (name: string | null | undefined) => (name ? `O Mac “${name}”` : "O Mac que roda o studio");
 
 export function offlineAdvice(o: {
@@ -22,22 +29,25 @@ export function offlineAdvice(o: {
       text: `${theMac(p.host || o.name)} tentou conectar em ${formatDayTime(p.at)}, mas o servidor não aceitou a chave dele. Ele pede uma nova sozinho: a página de aprovação abre no navegador do Mac.`,
       steps: [
         { text: "No Mac, aprove a conexão na página que abriu (entre com o Google se ela pedir)." },
-        { text: "Se a página não abriu, no Mac:", code: "node tools/runner.mjs login" },
+        { text: "Se a página não abriu, no Mac:", code: `${CLI} login` },
       ],
     };
   if (p?.reason === "revoked")
     return {
       title: "Este Mac foi desconectado",
       text: `${theMac(p.name || o.name)} foi desconectado do studio em ${formatDayTime(p.at)}. Ele só volta quando for pareado de novo.`,
-      steps: [{ text: "No Mac:", code: "node tools/runner.mjs login" }],
+      steps: [
+        { text: "No Mac:", code: `${CLI} login` },
+        { text: "Se o studio roda do repositório:", code: "node tools/runner.mjs login" },
+      ],
     };
   if (p?.reason === "protocol" && p.side === "mac")
     return {
       title: "O Mac precisa de atualização",
       text: `${theMac(p.host || o.name)} está com uma versão do studio anterior à do servidor, e os dois não se entendem.`,
       steps: [
-        { text: "No Mac, atualize e reinicie o studio:", code: "git pull && node tools/runner.mjs service restart" },
-        { text: "Sem o serviço, feche o studio e abra de novo:", code: "cd studio && bun start" },
+        { text: "No Mac, atualize o OmniVideo (ele reinicia o studio sozinho):", code: `${CLI}@latest up` },
+        { text: "Se o studio roda do repositório:", code: "git pull && node tools/runner.mjs service restart" },
       ],
     };
   if (p?.reason === "protocol")
@@ -48,12 +58,26 @@ export function offlineAdvice(o: {
         { text: "Suba o servidor: o merge na main faz o deploy sozinho, ou GitHub → Actions → Deploy → Run workflow." },
       ],
     };
+  /* the hub has never seen a Mac for this account: the first run, so the way in is the install */
+  if (!o.name && !o.lastSeen)
+    return {
+      title: "Falta ligar o OmniVideo no seu Mac",
+      text: "O vídeo é feito no seu computador (a narração, o motion e a montagem), e este studio só mostra e comanda. Nenhum Mac entrou nesta conta ainda.",
+      steps: [
+        { text: "Instale o plugin no Claude Code (uma vez):", code: PLUGIN_INSTALL },
+        {
+          text: "Abra uma sessão do Claude Code. O plugin abre o navegador para você aprovar o Mac, baixa o que o vídeo precisa (alguns minutos) e liga o studio sozinho. Esta tela some quando ele conectar.",
+        },
+        { text: "Sem o plugin, pelo terminal:", code: `${CLI} setup` },
+      ],
+    };
   return {
     title: "O studio perdeu a conexão",
     text: `${theMac(o.name)} não está conectado ${o.lastSeen ? `desde ${formatDayTime(o.lastSeen)}` : "agora"}. Ele pode estar desligado, dormindo ou sem internet, ou o studio está fechado. O que você pediu espera e volta a andar quando ele reconectar.`,
     steps: [
       { text: "Confira se o Mac está ligado, acordado e com internet." },
-      { text: "Deixe o studio sempre aberto (uma vez só, no Mac):", code: "node tools/runner.mjs service install" },
+      { text: "Deixe o studio sempre aberto (uma vez só, no Mac):", code: `${CLI} up` },
+      { text: "Se o studio roda do repositório:", code: "node tools/runner.mjs service install" },
       { text: "Ou abra à mão:", code: "cd studio && bun start" },
     ],
   };

package/tools/job-queue.mjs

@@ -25,17 +25,19 @@ import {
 } from "node:fs";
 import { join, dirname } from "node:path";
 import { CODE_ROOT, DATA_ROOT as ROOT } from "./lib/paths.mjs";
+import { IS_WINDOWS, pickPython, sleepSync } from "./lib/platform.mjs";
 
 const CFG = JSON.parse(readFileSync(join(ROOT, "omnivideo.config.json"), "utf8"));
 const QUEUE_DIR = join(ROOT, ".queue");
 
-/* a zombie counts as dead (see studio/api/services/queue.ts) */
+/* a zombie counts as dead (see studio/api/services/queue.ts); Windows has none, and no `ps` */
 function alive(pid) {
   try {
     process.kill(pid, 0);
   } catch (e) {
     if (e.code !== "EPERM") return false;
   }
+  if (IS_WINDOWS) return true;
   const ps = spawnSync("ps", ["-o", "stat=", "-p", String(pid)], { encoding: "utf8" });
   return !String(ps.stdout).trim().startsWith("Z");
 }
@@ -86,6 +88,19 @@ function mirror(log) {
   }
 }
 
+/* the atomic swap. On Windows a reader that has the ticket open (the guardian's Python, without share-delete)
+   makes the rename fail for a moment: try again, synchronously, because this runs on 'exit' */
+function swap(tmp, file) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return renameSync(tmp, file);
+    } catch (e) {
+      if (!IS_WINDOWS || attempt >= 24 || !["EPERM", "EACCES", "EBUSY"].includes(e.code)) throw e;
+      sleepSync(20);
+    }
+  }
+}
+
 /* on 'exit' only synchronous code runs; death by signal doesn't pass here, and
    the guardian closes the ticket as interrupted */
 function close(file, exitCode) {
@@ -98,7 +113,7 @@ function close(file, exitCode) {
     });
     const tmp = join(dirname(file), `.${ticket.id}.${process.pid}.tmp`);
     writeFileSync(tmp, JSON.stringify(ticket, null, 1) + "\n");
-    renameSync(tmp, file);
+    swap(tmp, file);
   } catch {
     /* the guardian closes it */
   }
@@ -128,10 +143,8 @@ function checkVoicePause(tool, dir) {
 export async function turn(tool, dir) {
   checkVoicePause(tool, dir);
   if (process.env.OMNIVIDEO_QUEUE === "0" || insideTurn()) return null;
-  /* the project's Python (.venv); without it, the config's and the system python3 */
-  const python =
-    [join(CODE_ROOT, ".venv", "bin", "python"), CFG.voicestudio?.python ?? ""].find(p => p && existsSync(p)) ??
-    "python3";
+  /* the project's Python (.venv, laid out per OS); without it, the config's and the system python3 */
+  const python = pickPython(CODE_ROOT, [CFG.voicestudio?.python ?? ""]);
   const guardian = spawn(
     python,
     [
@@ -143,7 +156,12 @@ export async function turn(tool, dir) {
       "--",
       ...process.argv.slice(1),
     ],
-    { stdio: ["pipe", "pipe", "inherit"] },
+    {
+      stdio: ["pipe", "pipe", "inherit"],
+      windowsHide: true,
+      /* Windows Python writes the ticket and its notices in the console's code page unless told */
+      env: IS_WINDOWS ? { ...process.env, PYTHONUTF8: "1" } : process.env,
+    },
   );
   const ticket = await new Promise((resolveTicket, reject) => {
     let buf = "";

package/tools/job_queue.py

@@ -14,9 +14,10 @@ In the Python tools:
 
 Heavy: voice, captions, final render, sound, assembly and Premiere
 (assemble, check, export). Each writes a ticket, .queue/<id>.json, and waits to
-be the oldest live one waiting; then it takes the flock on .queue/machine.lock.
-The kernel releases the flock when the process dies, even on kill -9: there is
-no forgotten lock. The task output also goes to .queue/<id>.log.
+be the oldest live one waiting; then it takes the lock on .queue/machine.lock
+(flock on macOS and Linux, msvcrt.locking on Windows). The kernel releases the
+lock when the process dies, even on kill -9: there is no forgotten lock. The
+task output also goes to .queue/<id>.log.
 
 The studio only reads this dir. Running, stopped or restarting in the middle of
 a task, the queue is the same.
@@ -26,10 +27,8 @@ holding the turn passes to its children, keeps a child from waiting for its own
 parent's turn.
 """
 
-import fcntl
 import json
 import os
-import select
 import shlex
 import signal
 import subprocess
@@ -42,6 +41,12 @@ from pathlib import Path
 
 from omni_paths import DATA_ROOT as ROOT
 
+IS_WINDOWS = sys.platform == "win32"
+if IS_WINDOWS:
+    import msvcrt
+else:
+    import fcntl
+
 QUEUE_DIR = ROOT / ".queue"
 LOCK = QUEUE_DIR / "machine.lock"
 
@@ -56,9 +61,35 @@ def now():
     return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
 
 
+def alive_windows(pid):
+    """os.kill(pid, 0) is not a probe on Windows: signal 0 is CTRL_C_EVENT, sent to the process group.
+    Ask the kernel instead: the process exists and has not exited (STILL_ACTIVE)."""
+    import ctypes
+    from ctypes import wintypes
+
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel32.OpenProcess.restype = wintypes.HANDLE
+    kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    kernel32.GetExitCodeProcess.argtypes = [wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD)]
+    kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    handle = kernel32.OpenProcess(0x1000, False, pid)  # PROCESS_QUERY_LIMITED_INFORMATION
+    if not handle:
+        # ERROR_ACCESS_DENIED: it exists and is not ours to open; anything else (invalid parameter): gone
+        return ctypes.get_last_error() == 5
+    try:
+        code = wintypes.DWORD()
+        if not kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
+            return True
+        return code.value == 259  # STILL_ACTIVE
+    finally:
+        kernel32.CloseHandle(handle)
+
+
 def alive(pid):
     if not pid:
         return False
+    if IS_WINDOWS:
+        return alive_windows(pid)
     try:
         os.kill(pid, 0)
     except ProcessLookupError:
@@ -78,8 +109,19 @@ def write(ticket):
     """Atomic swap: a reader never gets a half-written ticket."""
     dest = ticket_path(ticket["id"])
     tmp = dest.with_name(f".{ticket['id']}.{os.getpid()}.tmp")
-    tmp.write_text(json.dumps(ticket, ensure_ascii=False, indent=1) + "\n")
-    tmp.replace(dest)
+    tmp.write_text(json.dumps(ticket, ensure_ascii=False, indent=1) + "\n", encoding="utf-8")
+    if not IS_WINDOWS:
+        tmp.replace(dest)
+        return
+    # a reader that has the destination open (without share-delete) makes the replace fail for a moment
+    for attempt in range(25):
+        try:
+            tmp.replace(dest)
+            return
+        except PermissionError:
+            if attempt == 24:
+                raise
+            time.sleep(0.02)
 
 
 def read_all():
@@ -90,7 +132,7 @@ def read_all():
     tickets = []
     for p in QUEUE_DIR.glob("*.json"):
         try:
-            ticket = json.loads(p.read_text())
+            ticket = json.loads(p.read_text(encoding="utf-8"))
             mtime = p.stat().st_mtime
         except (OSError, ValueError):
             continue
@@ -109,7 +151,7 @@ def sort_key(ticket):
 def close_dead(id_):
     """Re-read after learning the owner died: what it wrote before exiting stands."""
     try:
-        ticket = json.loads(ticket_path(id_).read_text())
+        ticket = json.loads(ticket_path(id_).read_text(encoding="utf-8"))
     except (OSError, ValueError):
         return
     if ticket.get("state") in ACTIVE:
@@ -128,7 +170,7 @@ def prune():
         for p in (ticket_path(ticket["id"]), QUEUE_DIR / f"{ticket['id']}.log"):
             try:
                 p.unlink()
-            except FileNotFoundError:
+            except (FileNotFoundError, PermissionError):
                 pass
 
 
@@ -205,9 +247,25 @@ def summary(ticket):
     return f"{ticket['tool']} · {ticket.get('video') or '-'} ({who}, pid {ticket['pid']})"
 
 
+def try_lock(fd):
+    """Takes the machine lock if it is free, without waiting. True when it is ours now."""
+    if IS_WINDOWS:
+        os.lseek(fd, 0, os.SEEK_SET)
+        try:
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+        except OSError:
+            return False
+        return True
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        return True
+    except BlockingIOError:
+        return False
+
+
 def wait(ticket, fd, pause):
     """Returns the seconds waited when this ticket is the oldest live one waiting
-    and the flock is its own; None if `pause` gives up midway."""
+    and the lock is its own; None if `pause` gives up midway."""
     t0 = time.time()
     said = None
     lock_held_since = None
@@ -218,12 +276,8 @@ def wait(ticket, fd, pause):
             for t in tickets
             if t["effective"] == "waiting" and t["id"] != ticket["id"] and sort_key(t) < sort_key(ticket)
         ]
-        if not ahead:
-            try:
-                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
-                return time.time() - t0
-            except BlockingIOError:
-                pass
+        if not ahead and try_lock(fd):
+            return time.time() - t0
         running = [t for t in tickets if t["effective"] == "running"]
         # lock busy with nobody running is usually the handover between two tasks
         # (Node closes the ticket an instant before the guardian releases the lock)
@@ -245,7 +299,7 @@ def wait(ticket, fd, pause):
 def begin(ticket, waited):
     ticket.update(state="running", started_at=now())
     write(ticket)
-    # with the flock in hand, another "running" ticket can only belong to a dead process
+    # with the lock in hand, another "running" ticket can only belong to a dead process
     for t in read_all():
         if t["id"] != ticket["id"] and t["state"] == "running" and not alive(t.get("pid")):
             close_dead(t["id"])
@@ -291,7 +345,7 @@ def inside_turn():
     if not id_:
         return False
     try:
-        ticket = json.loads(ticket_path(id_).read_text())
+        ticket = json.loads(ticket_path(id_).read_text(encoding="utf-8"))
     except (OSError, ValueError):
         return False
     return ticket.get("state") == "running" and alive(ticket.get("pid"))
@@ -354,13 +408,35 @@ def turn(tool, dir=None):
             del os.environ["OMNIVIDEO_TURN"]
 
 
+class StdinWatcher(threading.Thread):
+    """Reads the pipe from the Node process until it closes. A thread because select() on a pipe is
+    POSIX only; `closed` is set when the Node process is gone, in any way."""
+
+    def __init__(self):
+        super().__init__(daemon=True)
+        self.closed = threading.Event()
+        self.start()
+
+    def run(self):
+        try:
+            while os.read(0, 4096):
+                pass
+        except OSError:
+            pass
+        self.closed.set()
+
+
 def guardian(tool, dir, pid, command):
     """Holds the turn of a Node process (tools/job-queue.mjs).
 
     Waits like any task; on its turn, writes one JSON line to stdout and keeps
     reading stdin, which is a pipe from the Node process. The pipe closes when
-    it exits, in any way, and then the ticket is closed and the flock released.
+    it exits, in any way, and then the ticket is closed and the lock released.
     """
+    if IS_WINDOWS:
+        # the pipe to Node carries text in the console's code page unless told otherwise
+        for stream in (sys.stdout, sys.stderr):
+            stream.reconfigure(encoding="utf-8")
     # Ctrl-C kills Node; the guardian stays to close the ticket when the pipe closes
     signal.signal(signal.SIGINT, signal.SIG_IGN)
     signal.signal(signal.SIGTERM, signal.SIG_IGN)
@@ -369,9 +445,10 @@ def guardian(tool, dir, pid, command):
     heartbeat = Heartbeat(ticket["id"])
     fd = os.open(LOCK, os.O_RDWR | os.O_CREAT, 0o644)
 
+    watcher = StdinWatcher()
+
     def pause(seconds):
-        readable, _, _ = select.select([0], [], [], seconds)
-        return not (readable and not os.read(0, 4096))
+        return not watcher.closed.wait(seconds)
 
     waited = wait(ticket, fd, pause)
     if waited is None:
@@ -383,8 +460,7 @@ def guardian(tool, dir, pid, command):
             json.dumps({"id": ticket["id"], "file": str(ticket_path(ticket["id"])), "log": str(ROOT / ticket["log"])}),
             flush=True,
         )
-        while os.read(0, 4096):
-            pass
+        watcher.closed.wait()
         close_dead(ticket["id"])
     heartbeat.stop()
     os.close(fd)

package/tools/lib/agents.mjs

@@ -54,7 +54,12 @@ export const expandHome = p =>
       .trim()
       .replace(/^~(?=\/|$)/, homedir()),
   );
-export const tildify = p => (p.startsWith(homedir()) ? `~${p.slice(homedir().length)}` : p);
+/* on Windows the folder is written `~/…` too (expandHome only expands `~/`), so it reads back the same */
+export const tildify = p => {
+  if (!p.startsWith(homedir())) return p;
+  const rest = p.slice(homedir().length);
+  return `~${process.platform === "win32" ? rest.replace(/\\/g, "/") : rest}`;
+};
 
 function readJson(file) {
   try {

package/tools/lib/deps.mjs

@@ -30,6 +30,9 @@ import {
 import { homedir, tmpdir } from "node:os";
 import { delimiter, join } from "node:path";
 import { gunzipSync } from "node:zlib";
+import { venvPython } from "./platform.mjs";
+
+export { venvPython };
 
 export const OMNI_DIR = process.env.OMNI_DIR || join(homedir(), ".omni");
 export const BIN_DIR = join(OMNI_DIR, "bin");
@@ -44,10 +47,6 @@ const exe = (/** @type {string} */ name) => (win ? `${name}.exe` : name);
 /* ffmpeg-static has no Windows arm64 build: the x64 one runs under emulation */
 const arch = () => (process.arch === "arm64" && !win ? "arm64" : "x64");
 
-/** the app's venv Python, as each OS lays a venv out  @param {string} codeRoot */
-export const venvPython = codeRoot =>
-  win ? join(codeRoot, ".venv", "Scripts", "python.exe") : join(codeRoot, ".venv", "bin", "python");
-
 /** @returns {{ chrome?: string }} */
 const readState = () => {
   try {
@@ -163,8 +162,10 @@ async function ensureUv() {
       join(tmp, archive),
       await fetchBytes(`https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/${archive}`),
     );
-    /* tar reads both .tar.gz and .zip on macOS and Windows 10+, and .tar.gz on Linux */
-    const x = spawnSync("tar", ["-xf", archive], { cwd: tmp, encoding: "utf8" });
+    /* tar reads both .tar.gz and .zip on macOS and Windows 10+, and .tar.gz on Linux. On Windows it is the
+       system's own bsdtar: a Git Bash `tar` earlier on PATH is GNU tar, which can't open a .zip */
+    const tar = win ? join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe") : "tar";
+    const x = spawnSync(tar, ["-xf", archive], { cwd: tmp, encoding: "utf8" });
     if (x.status !== 0) throw new Error(`não consegui abrir o ${archive}: ${x.stderr.trim()}`);
     const found = readdirSync(tmp, { recursive: true, withFileTypes: true }).find(
       e => e.isFile() && e.name === exe("uv"),
@@ -177,6 +178,17 @@ async function ensureUv() {
   return file;
 }
 
+/** the arguments that make the app's venv  @param {string} codeRoot */
+export const uvVenvArgs = codeRoot => [
+  "venv",
+  "--python",
+  PYTHON_VERSION,
+  "--python-preference",
+  "only-managed",
+  "--allow-existing",
+  join(codeRoot, ".venv"),
+];
+
 /** the venv with requirements.txt installed  @param {string} codeRoot */
 export async function ensurePython(codeRoot) {
   const python = venvPython(codeRoot);
@@ -187,10 +199,9 @@ export async function ensurePython(codeRoot) {
     UV_PYTHON_INSTALL_DIR: join(OMNI_DIR, "python"),
     UV_CACHE_DIR: join(OMNI_DIR, "uv-cache"),
   };
-  const venv = spawnSync(uv, ["venv", "--python", PYTHON_VERSION, "--allow-existing", join(codeRoot, ".venv")], {
-    encoding: "utf8",
-    env,
-  });
+  /* only-managed: the venv's Python is always uv's own build, never one found on the machine (on Windows the
+     Microsoft Store's python.exe stub, which opens the Store instead of running) */
+  const venv = spawnSync(uv, uvVenvArgs(codeRoot), { encoding: "utf8", env });
   if (venv.status !== 0) throw new Error(`uv venv falhou: ${venv.stderr.trim().split("\n").at(-1)}`);
   const pip = spawnSync(uv, ["pip", "install", "--python", python, "-r", join(codeRoot, "requirements.txt")], {
     encoding: "utf8",