@hypit/hypit 0.1.7 → 0.1.9

package/packages/runtime-local/src/programs.ts

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 
 import type { CapabilityRef } from "@hypit/protocol";
@@ -30,6 +30,8 @@ export type ManagedProgramReport = {
   /** Why the action fell short. Never a copy of what `state` already says. */
   readonly detail?: string;
   readonly logPath?: string;
+  readonly installationLogPath?: string;
+  readonly errorLogPath?: string;
   readonly pid?: number;
 };
 
@@ -37,6 +39,7 @@ export type ManagedProgramProgress = {
   readonly id: string;
   readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready";
   readonly logPath?: string;
+  readonly detail?: string;
 };
 
 export type ManagedProgramOptions = LoadRuntimeConfigOptions & {
@@ -99,9 +102,40 @@ async function readPid(root: string, program: ManagedProgram): Promise<number |
   }
 }
 
+async function existingLogs(root: string, program: ManagedProgram) {
+  const home = directory(root, program);
+  const paths = {
+    logPath: join(home, "program.log"),
+    installationLogPath: join(home, "install.log"),
+    ...(process.platform === "win32" ? { errorLogPath: processErrorLogPath(join(home, "program.log")) } : {}),
+  };
+  const found: { logPath?: string; installationLogPath?: string; errorLogPath?: string } = {};
+  for (const [key, path] of Object.entries(paths)) {
+    try { await stat(path); found[key as keyof typeof found] = path; }
+    catch (error) { if (!nodeError(error, "ENOENT")) throw error; }
+  }
+  return found;
+}
+
+async function programReport(root: string, program: ManagedProgram, endpoint: string): Promise<ManagedProgramReport> {
+  const state = await program.probe();
+  const pid = await readPid(root, program);
+  return { id: program.id, endpoint, state, ...await existingLogs(root, program),
+    ...(pid !== undefined && processAlive(pid) ? { pid } : {}),
+  };
+}
+
+function commandLabel(command: ManagedProgramCommand): string {
+  // Labels describe purpose. Arguments and environment values can contain credentials.
+  return (command.label ?? basename(command.command)).replace(/\s+/gu, " ").trim();
+}
+
 async function run(root: string, command: ManagedProgramCommand, logPath: string): Promise<{ ok: boolean; detail: string }> {
   const log = await open(logPath, "a+");
   try {
+    const started = Date.now();
+    const label = commandLabel(command);
+    await log.appendFile(`\n${new Date().toISOString()} Starting: ${label}\n`);
     const offset = (await log.stat()).size;
     const exit = await new Promise<{ code: number | null; error?: string }>((resolve) => {
       const child = spawn(command.command, [...command.args], {
@@ -114,25 +148,24 @@ async function run(root: string, command: ManagedProgramCommand, logPath: string
       child.on("error", (error) => resolve({ code: null, error: error.message }));
       child.on("close", (code) => resolve({ code }));
     });
-    if (exit.code === 0) return { ok: true, detail: "" };
+    if (exit.code === 0) {
+      await log.appendFile(`${new Date().toISOString()} Finished: ${label} (${((Date.now() - started) / 1000).toFixed(1)}s)\n`);
+      return { ok: true, detail: "" };
+    }
     const end = (await log.stat()).size;
     const start = Math.max(offset, end - 8192);
     const tail = Buffer.alloc(end - start);
     const { bytesRead } = await log.read(tail, 0, tail.length, start);
     const line = tail.subarray(0, bytesRead).toString().trim().split(/\r?\n/u).at(-1);
+    await log.appendFile(`${new Date().toISOString()} Failed: ${label} (${((Date.now() - started) / 1000).toFixed(1)}s)\n`);
     return { ok: false, detail: exit.error ?? (line || `exited ${exit.code}`) };
   } finally {
     await log.close();
   }
 }
 
-/**
- * Poll until the program answers as itself. `down` is expected while it loads
- * weights; `mismatch` is not, and stops the wait — a program that is answering
- * with another identity will not become the right one by waiting.
- */
 /** POSIX: its own session, and stdio already pointed at the log. */
-async function startDetached(start: ManagedProgramCommand, root: string, logFd: number): Promise<number | undefined> {
+async function startDetached(start: ManagedProgramCommand, root: string, logFd: number): Promise<{ pid?: number; detail?: string }> {
   const child = spawn(start.command, [...start.args], {
     cwd: start.cwd ?? root,
     env: { ...process.env, ...start.env },
@@ -141,8 +174,13 @@ async function startDetached(start: ManagedProgramCommand, root: string, logFd:
     windowsHide: true,
     stdio: ["ignore", logFd, logFd],
   });
-  child.unref();
-  return child.pid;
+  return await new Promise((resolve) => {
+    child.once("error", (error) => resolve({ detail: error.message }));
+    child.once("spawn", () => {
+      child.unref();
+      resolve(child.pid === undefined ? { detail: "spawn reported no process id" } : { pid: child.pid });
+    });
+  });
 }
 
 /** A PowerShell single-quoted literal, which escapes by doubling the quote and nothing else. */
@@ -243,11 +281,12 @@ async function waitForReady(program: ManagedProgram, pid: number, maxWaitMs: num
   return state;
 }
 
-async function bringUp(
+async function bringUpOwned(
   root: string,
   program: ManagedProgram,
   endpoint: string,
   maxWaitMs: number,
+  release: () => void,
   onProgress?: (event: ManagedProgramProgress) => void,
 ): Promise<ManagedProgramReport> {
   const base = { id: program.id, endpoint };
@@ -265,13 +304,28 @@ async function bringUp(
   let installed = false;
   const logPath = join(directory(root, program), "program.log");
   const installLogPath = join(directory(root, program), "install.log");
+  const existingPid = await readPid(root, program);
+  if (existingPid !== undefined && processAlive(existingPid)) {
+    release();
+    onProgress?.({ id: program.id, phase: "waiting", logPath,
+      detail: `observing existing process ${existingPid}` });
+    const state = await waitForReady(program, existingPid, maxWaitMs);
+    const alive = processAlive(existingPid);
+    return { ...base, action: state.state === "ready" ? "already-running" : "unchanged", state, logPath,
+      ...(alive ? { pid: existingPid } : {}),
+      ...(state.state === "ready" ? {} : { detail: alive
+        ? `process ${existingPid} is still running; readiness has not been established; see ${logPath}`
+        : `process exited; see ${logPath}` }),
+    };
+  }
+  if (existingPid !== undefined) await rm(join(directory(root, program), "process.pid"), { force: true });
   if (program.installation !== undefined) {
     const installation = await program.installation.probe();
     if (installation.state !== "ready" || program.installation.prepareBeforeStart === true) {
       await mkdir(directory(root, program), { recursive: true });
       await rotateLog(installLogPath);
-      onProgress?.({ id: program.id, phase: "installing", logPath: installLogPath });
       for (const command of program.installation.commands) {
+        onProgress?.({ id: program.id, phase: "installing", logPath: installLogPath, detail: commandLabel(command) });
         const result = await run(root, command, installLogPath);
         if (!result.ok) {
           return { ...base, action: "unchanged", state: initial, logPath: installLogPath, detail: `${command.command} failed: ${result.detail}` };
@@ -317,7 +371,7 @@ async function bringUp(
     // creates a new console and hides it, which is the combination neither spawn option reaches.
     const started = process.platform === "win32"
       ? await startWithOwnConsole(program.start, root, logPath)
-      : { pid: await startDetached(program.start, root, log.fd) };
+      : await startDetached(program.start, root, log.fd);
     if (started.pid === undefined) {
       const refusal = "detail" in started && started.detail !== undefined ? `: ${started.detail}` : "";
       return {
@@ -329,11 +383,27 @@ async function bringUp(
       };
     }
     const child = { pid: started.pid };
+    // Publish ownership before observing readiness. Another up can now reuse this process,
+    // and down can stop it even if loading is slow. The observation owns no startup lock.
+    const pidPath = join(directory(root, program), "process.pid");
+    // Under the startup lock the old record is already absent. Rename publishes a complete
+    // record to read-only observers without replacing a file they might have open on Windows.
+    await writeFile(`${pidPath}.tmp`, `${child.pid}\n`);
+    await rename(`${pidPath}.tmp`, pidPath);
+    release();
     onProgress?.({ id: program.id, phase: "waiting" });
     const state = await waitForReady(program, child.pid, maxWaitMs);
     if (state.state === "ready") onProgress?.({ id: program.id, phase: "ready" });
     const alive = processAlive(child.pid);
-    if (alive) await writeFile(join(directory(root, program), "process.pid"), `${child.pid}\n`);
+    if (!alive) {
+      const { tryProgramLock } = await import("./program-lock.js");
+      const releaseCleanup = tryProgramLock(directory(root, program));
+      if (releaseCleanup !== undefined) {
+        try {
+          if (await readPid(root, program) === child.pid) await rm(pidPath, { force: true });
+        } finally { releaseCleanup(); }
+      }
+    }
     return {
       ...base,
       action: state.state === "ready" ? (alive ? "started" : "already-running") : "unchanged",
@@ -341,7 +411,7 @@ async function bringUp(
       ...(alive ? { pid: child.pid } : {}),
       logPath,
       ...(state.state === "ready" ? {} : {
-        detail: alive ? `see ${logPath}` : `process exited; see ${logPath}`,
+        detail: alive ? `process ${child.pid} is still running; readiness has not been established; see ${logPath}` : `process exited; see ${logPath}`,
       }),
     };
   } finally {
@@ -349,6 +419,22 @@ async function bringUp(
   }
 }
 
+async function bringUp(
+  root: string, program: ManagedProgram, endpoint: string, maxWaitMs: number,
+  onProgress?: (event: ManagedProgramProgress) => void,
+): Promise<ManagedProgramReport> {
+  const home = directory(root, program);
+  await mkdir(home, { recursive: true });
+  const { tryProgramLock } = await import("./program-lock.js");
+  const release = tryProgramLock(home);
+  if (release === undefined) return { ...await programReport(root, program, endpoint), action: "unchanged",
+    detail: "another command owns this Program's preparation or lifecycle change; inspect its logs", };
+  try {
+    const report = await bringUpOwned(root, program, endpoint, maxWaitMs, release, onProgress);
+    return { ...await existingLogs(root, program), ...report };
+  } finally { release(); }
+}
+
 /** Install when needed and start every external program the Runtime Profile implies. */
 export async function bringManagedProgramsUp(
   path: string,
@@ -371,60 +457,68 @@ export async function takeManagedProgramsDown(
   const { dataRoot, programs } = await declaredManagedPrograms(path, options);
   const reports = await Promise.all(independentPrograms(programs).map(async ({ instance, program }): Promise<ManagedProgramReport> => {
     const base = { id: program.id, endpoint: instance };
-    const pid = await readPid(dataRoot, program);
-    if (pid === undefined || !processAlive(pid)) {
-      if (pid !== undefined) await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
-      const state = await program.probe();
-      return state.state === "down"
-        ? { ...base, action: "nothing-to-stop", state }
-        // Someone else's process, or one started by hand. Killing it is not this
-        // command's business; saying so is.
-        : { ...base, action: "not-ours", state, detail: `${program.id} is running without a Hypit process record` };
-    }
-    const term = await stopProcessTree(pid);
-    if (term === "denied") {
-      return {
-        ...base,
-        action: "unchanged",
-        state: await program.probe(),
-        pid,
-        detail: `process ${pid} is running but this environment cannot stop it`,
-      };
-    }
-    if (term === "gone") {
-      await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
-      const state = await program.probe();
-      return state.state === "down"
-        ? { ...base, action: "nothing-to-stop", state }
-        : { ...base, action: "not-ours", state, detail: `${program.id} is now served by another process` };
-    }
-    const deadline = Date.now() + 15_000;
-    while (processAlive(pid) && Date.now() < deadline) await sleep(200);
-    if (processAlive(pid)) {
-      if (await stopProcessTree(pid, true) === "denied") {
+    const home = directory(dataRoot, program);
+    await mkdir(home, { recursive: true });
+    const { tryProgramLock } = await import("./program-lock.js");
+    const release = tryProgramLock(home);
+    if (release === undefined) return { ...await programReport(dataRoot, program, instance), action: "unchanged",
+      detail: "another command owns this Program's preparation or lifecycle change; inspect its logs", };
+    try {
+      const pid = await readPid(dataRoot, program);
+      if (pid === undefined || !processAlive(pid)) {
+        if (pid !== undefined) await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
+        const state = await program.probe();
+        return state.state === "down"
+          ? { ...base, action: "nothing-to-stop", state }
+          // Someone else's process, or one started by hand. Killing it is not this
+          // command's business; saying so is.
+          : { ...base, action: "not-ours", state, detail: `${program.id} is running without a Hypit process record` };
+      }
+      const term = await stopProcessTree(pid);
+      if (term === "denied") {
         return {
           ...base,
           action: "unchanged",
           state: await program.probe(),
           pid,
-          detail: `process ${pid} ignored graceful termination and cannot be force-stopped`,
+          detail: `process ${pid} is running but this environment cannot stop it`,
         };
       }
-      const forceDeadline = Date.now() + 2_000;
-      while (processAlive(pid) && Date.now() < forceDeadline) await sleep(50);
+      if (term === "gone") {
+        await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
+        const state = await program.probe();
+        return state.state === "down"
+          ? { ...base, action: "nothing-to-stop", state }
+          : { ...base, action: "not-ours", state, detail: `${program.id} is now served by another process` };
+      }
+      const deadline = Date.now() + 15_000;
+      while (processAlive(pid) && Date.now() < deadline) await sleep(200);
       if (processAlive(pid)) {
-        return {
-          ...base,
-          action: "unchanged",
-          state: await program.probe(),
-          pid,
-          detail: `process ${pid} remained alive after forced termination`,
-        };
+        if (await stopProcessTree(pid, true) === "denied") {
+          return {
+            ...base,
+            action: "unchanged",
+            state: await program.probe(),
+            pid,
+            detail: `process ${pid} ignored graceful termination and cannot be force-stopped`,
+          };
+        }
+        const forceDeadline = Date.now() + 2_000;
+        while (processAlive(pid) && Date.now() < forceDeadline) await sleep(50);
+        if (processAlive(pid)) {
+          return {
+            ...base,
+            action: "unchanged",
+            state: await program.probe(),
+            pid,
+            detail: `process ${pid} remained alive after forced termination`,
+          };
+        }
       }
-    }
-    await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
-    return { ...base, action: "stopped", state: await program.probe(), pid };
-    }));
+      await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
+      return { ...base, action: "stopped", state: await program.probe(), pid };
+    } finally { release(); }
+  }));
   return { dataRoot, programs: reports };
 }
 
@@ -434,24 +528,7 @@ export async function reportManagedPrograms(
   options: ManagedProgramOptions = {},
 ): Promise<{ readonly dataRoot: string; readonly programs: readonly ManagedProgramReport[] }> {
   const { dataRoot, programs } = await declaredManagedPrograms(path, options);
-  const reports = await Promise.all(independentPrograms(programs).map(async ({ instance, program }): Promise<ManagedProgramReport> => {
-    const state = await program.probe();
-    const pid = await readPid(dataRoot, program);
-    const logPath = join(directory(dataRoot, program), "program.log");
-    let hasLog = false;
-    try {
-      await stat(logPath);
-      hasLog = true;
-    } catch (error) {
-      if (!nodeError(error, "ENOENT")) throw error;
-    }
-    return {
-      id: program.id,
-      endpoint: instance,
-      state,
-      ...(pid !== undefined && processAlive(pid) ? { pid } : {}),
-      ...(hasLog ? { logPath } : {}),
-    };
-  }));
+  const reports = await Promise.all(independentPrograms(programs).map(async ({ instance, program }) =>
+    await programReport(dataRoot, program, instance)));
   return { dataRoot, programs: reports };
 }

package/packages/video-cli/README.md

@@ -11,15 +11,38 @@ reusable Source directly, for example
 `<import as="ugc" source="@hypit/gpt-image-kits/phone-ugc-v1"/>`; resolving that Source does not
 activate package code.
 
-From any project:
+`hypit version` reports the Distribution version, physical root and launcher independently of a
+project or Runtime. `hypit version --check` also reads the package's `latest` tag at
+`https://registry.npmjs.org/`; `--registry <url>` explicitly selects another registry. `--json`
+returns `hypit.cli-version@1`. A failed check retains local facts, leaves the remote version unknown
+and exits nonzero. A different version is not automatically newer: the launcher may be a newer
+checkout or the mirror may lag. The command links release notes and never installs or updates.
+Skill installers own their separate installed copies; this command does not scan Agent directories.
+`hypit --version` remains a local version-only query.
+
+Commands below serve independent authoring decisions. Start with the current project's material;
+local inspection and estimation need no generation account:
 
 ```bash
 cd path/to/project
-hypit runtime init
-hypit auth login hypihub.default
-hypit doctor
-hypit runtime up
 hypit check main.svml
+hypit measure main.svml --segment hook --language en
+```
+
+When the work needs execution, the project selects a Runtime Profile. `hypit runtime init` creates
+an editable starter; its Endpoint entries describe available routes, not choices made by the user.
+Keep an existing chosen service, or configure the chosen local or hosted Provider and its capability
+bindings. HypiHub is the recommended integrated hosted route in the official Distribution; other
+services use project Provider packages. If the user chooses HypiHub,
+`hypit auth login hypihub.default` connects that account.
+`hypit doctor --endpoint <name>` checks a selected Endpoint;
+`hypit runtime up --endpoint <name>` prepares that Endpoint and starts the Worker. Repeat the flag
+for several chosen Endpoints; omitting it prepares the whole Profile. `hypit programs up --endpoint
+<name>` prepares a local helper independently of the Worker.
+
+With the selected execution environment:
+
+```bash
 hypit plan build.svrun
 hypit build build.svrun --follow
 hypit status <build-id> --watch
@@ -29,7 +52,6 @@ hypit history <source-output-name> [--source ./main.svml]
 hypit inspect <build-id> [--output <source-output-name>]
 hypit get <build-id> --output final.video --to ./final.mp4
 hypit cancel <build-id>
-hypit doctor
 ```
 
 `transcribe` runs one immediate request through the selected Runtime Profile, with no Build,
@@ -63,6 +85,11 @@ that produced them, so they are declared in the Source and go through `plan` and
 voice or learn a passage's real length before authoring the rest, build a Run whose target is that
 speech output and reuse it as a Candidate.
 
+Provider selection is checked before `transcribe` invokes the service. Multiple matching Endpoints
+can remain in the Profile: `bindings` chooses one for the capability. An unsupported request reports
+the selected binding and Provider-owned rejection reasons so the author can adjust the request or
+choose a compatible Endpoint. It does not imply that an account needs payment or login.
+
 Two more families are local, stateless and spend nothing. `hypit media` exposes the source at chosen
 times and scales, and `hypit vocabulary`
 prints what a Source may write:

package/packages/video-cli/src/cli.ts

@@ -5,6 +5,7 @@ import { creationCommands, isCreationCommand, writeCreationHelp } from "./creati
 import { isMediaCommand, mediaCommands, writeMediaHelp } from "./media.js";
 import { writeVocabularyHelp } from "./vocabulary.js";
 import { writeCaptureHelp } from "./capture.js";
+import { runVersionCli, writeVersionHelp } from "./version.js";
 
 const argv = process.argv.slice(2);
 const json = argv.includes("--json");
@@ -67,6 +68,7 @@ async function main(): Promise<void> {
     const topic = argv[0] === "help" ? argv[1]
       : argv[0] === "--help" ? undefined
       : argv.includes("--help") ? argv[0] : undefined;
+    if (topic === "version") { writeVersionHelp(io); return; }
     if (isCreationCommand(topic)) {
       writeCreationHelp(io, topic);
       return;
@@ -86,12 +88,13 @@ async function main(): Promise<void> {
     }
     writeCliHelp(io, topic);
     if (topic === undefined) {
-      io.write(`\nCreation tools (one request through the selected Runtime Profile, no Build)\n${
+      io.write(`\nInstallation\n  version [--check] [--registry <url>] [--json]\n\nCreation tools (one request through the selected Runtime Profile, no Build)\n${
         creationCommands.map((item) => `  ${item}`).join("\n")}\n  hypit help <tool> for each\n`
         + `\nStudio\n  studio --run <build.svrun>\n  hypit studio --help for session options\n\nPreparation (local tools and project files)\n  media ${mediaCommands.join(" | ")}\n  capture screenshot | run | install-browser\n  vocabulary\n  hypit help media, hypit help capture, hypit help vocabulary\n`);
     }
     return;
   }
+  if (argv[0] === "version") { await runVersionCli(argv, io); return; }
   const { runVideoCli } = await import("./index.js");
   await runVideoCli(argv, io);
 }

package/packages/video-cli/src/creation.ts

@@ -159,9 +159,14 @@ async function selectedProvider(host: CreationHost, need: Need, profile: string)
   }]);
   const subject = capabilityName(need.capability);
   assert(provider !== undefined && provider.status !== "unresolved",
-    `No Endpoint in ${profile} serves ${subject}; hypit plan --runtime ${profile} shows which Endpoint each capability needs`);
+    `No Endpoint in ${profile} serves ${subject}; configure an Endpoint that supports this capability and check its binding in that Profile`);
   assert(provider.status !== "ambiguous",
-    `Several Endpoints in ${profile} serve ${subject}: ${(provider.endpoints ?? []).join(", ")}; keep exactly one`);
+    `Several Endpoints in ${profile} serve ${subject}: ${(provider.endpoints ?? []).join(", ")}; select one with bindings[${JSON.stringify(subject)}] in that Profile`);
+  assert(provider.status !== "unsupported",
+    `The configured Endpoints in ${profile} do not support this request for ${subject}`
+    + (provider.binding === undefined ? "" : ` (binding: ${provider.binding})`)
+    + `: ${(provider.rejections ?? []).map((item) => `${item.endpoint}: ${item.message}`).join("; ") || "no support reason supplied"}`
+    + "; adjust the request or select a compatible Endpoint in that Profile");
   return provider;
 }
 

package/packages/video-cli/src/index.ts

@@ -12,6 +12,7 @@ import { videoCliDistribution } from "./distribution.js";
 import { runMediaCli } from "./media.js";
 import { runVocabularyCli } from "./vocabulary.js";
 import { runCaptureCli } from "./capture.js";
+import { runVersionCli } from "./version.js";
 
 export {
   createVideoCompiler,
@@ -35,6 +36,7 @@ export function runVideoCli(
   io: CliIo,
   packages: readonly LoadedPackage[] = [],
 ): Promise<void> {
+  if (argv[0] === "version") return runVersionCli(argv, io);
   installDistributionPackageResolution(videoCliDistribution.packageRoot === undefined
     ? []
     : [videoCliDistribution.packageRoot]);

package/packages/video-cli/src/version.ts

@@ -0,0 +1,90 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { CliIo } from "@hypit/cli";
+import { requestDeadline } from "@hypit/runtime-kit";
+
+type VersionEnvironment = {
+  readonly packageRoot: string;
+  readonly launcher?: string;
+  readonly fetch: typeof globalThis.fetch;
+  readonly timeoutMs?: number;
+};
+
+export function writeVersionHelp(io: CliIo): void {
+  io.write("Usage: hypit version [--check] [--registry <url>] [--json]\n\n"
+    + "Show the executing Distribution and launcher without opening a project or Runtime.\n"
+    + "--check queries npm latest (registry.npmjs.org by default); --registry selects a mirror.\n"
+    + "No packages or Skills are updated. hypit --version remains a local version-only query.\n");
+}
+
+/** Installation discovery belongs to the executable, independent of video execution and Skill installers. */
+export async function runVersionCli(argv: readonly string[], io: CliIo, environment: VersionEnvironment = {
+  packageRoot: resolve(import.meta.dirname, "../../.."),
+  ...(process.env.HYPIT_CLI_LAUNCHER === undefined ? {} : { launcher: process.env.HYPIT_CLI_LAUNCHER }),
+  fetch: globalThis.fetch,
+}): Promise<void> {
+  let check = false;
+  let json = false;
+  let registry = "https://registry.npmjs.org/";
+  let selectedRegistry = false;
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--check") check = true;
+    else if (arg === "--json") json = true;
+    else if (arg === "--registry") {
+      selectedRegistry = true;
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("--")) throw new Error("--registry requires a URL");
+      const url = new URL(value);
+      if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new Error("--registry requires an HTTP(S) registry URL without credentials, query or fragment");
+      }
+      registry = `${url.href.replace(/\/+$/u, "")}/`;
+    } else if (arg === "--help") { writeVersionHelp(io); return; }
+    else if (arg !== "--no-color" && arg !== "--debug") throw new Error(`Unknown version option: ${arg}`);
+  }
+  if (selectedRegistry && !check) throw new Error("--registry selects the source for --check; add --check to query it");
+  const manifest = JSON.parse(await readFile(resolve(environment.packageRoot, "package.json"), "utf8")) as {
+    name: string; version: string; repository?: { url?: string };
+  };
+  const repository = manifest.repository?.url?.replace(/^git\+/u, "").replace(/\.git$/u, "");
+  const releases = repository === undefined ? undefined : `${repository}/releases`;
+  let latest: { registry: string; version?: string; matchesInstalled?: boolean; error?: string } | undefined;
+  if (check) {
+    latest = { registry };
+    const deadline = requestDeadline(environment.timeoutMs ?? 10_000,
+      () => new Error("Registry version query timed out; latest version is unknown"));
+    try {
+      const response = await deadline.wait(environment.fetch(new URL(`${encodeURIComponent(manifest.name)}/latest`, registry), {
+        signal: deadline.signal, headers: { accept: "application/json" },
+      }));
+      if (!response.ok) throw new Error(`Registry returned HTTP ${response.status}; latest version is unknown`);
+      const body = await deadline.wait(response.json()) as { name?: unknown; version?: unknown };
+      if (body.name !== manifest.name || typeof body.version !== "string" || body.version.length === 0) {
+        throw new Error("Registry returned no matching package version; latest version is unknown");
+      }
+      latest.version = body.version;
+      latest.matchesInstalled = body.version === manifest.version;
+    } catch (error) {
+      latest.error = error instanceof Error ? error.message : String(error);
+      io.setExitCode?.(1);
+    } finally { deadline.finish(); }
+  }
+  const report = {
+    format: "hypit.cli-version@1", package: manifest.name, version: manifest.version,
+    distribution: resolve(environment.packageRoot),
+    ...(environment.launcher === undefined ? {} : { launcher: resolve(environment.launcher) }),
+    ...(releases === undefined ? {} : { releases }),
+    ...(latest === undefined ? {} : { latest }),
+  };
+  if (json) { io.write(`${JSON.stringify(report, null, 2)}\n`); return; }
+  io.write(`${manifest.name} ${manifest.version}\nDistribution: ${report.distribution}\n`
+    + (report.launcher === undefined ? "" : `Launcher: ${report.launcher}\n`));
+  if (latest !== undefined) {
+    io.write(`npm latest: ${latest.version === undefined ? "unknown" : `${latest.version} (${latest.matchesInstalled ? "matches installed" : "differs from installed"})`}\nRegistry: ${registry}\n`);
+    if (latest.error !== undefined) io.write(`${latest.error}\n`);
+    if (releases !== undefined) io.write(`Release notes: ${releases}\n`);
+    io.write("Update through this installation's package manager or checkout; preserve the project's chosen version.\n"
+      + "Skill updates belong to its installer and are separate from this executable.\n");
+  }
+}

package/services/whisperx/README.md

@@ -19,8 +19,8 @@ semantic projection combines this evidence with one explicit Script Segment late
 ## Install
 
 For an ordinary installed Distribution, select the local WhisperX Endpoint and run
-`hypit runtime up`. The Runtime creates this environment in the machine Program Home only when it is
-missing, and reuses it across projects and sessions. The commands below are contributor/operator
+`hypit programs up --endpoint <instance>`. The Runtime creates or reconciles the cold environment in
+the machine Program Home and reuses a running service across projects and sessions. The commands below are contributor/operator
 diagnostics for a deliberately managed deployment:
 
 WhisperX 3.8.6 supports Python 3.10 through 3.13. The checked-in lock selects Python 3.13:
@@ -32,7 +32,8 @@ uv run --project services/whisperx --frozen hypit-whisperx-prepare
 uv run --project services/whisperx --frozen hypit-whisperx-check
 ```
 
-The first model start may download ASR and alignment weights. Production should put the relevant
+The first model start may download ASR weights; first use of a language can download its alignment
+model during the request. Production should put the relevant
 Hugging Face cache on persistent storage. `hypit-whisperx-prepare` separately installs NLTK's
 `punkt_tab` sentence data through NLTK's own downloader. This resource is required by WhisperX
 alignment and is prepared explicitly before the warm service starts, never inside an inference request.
@@ -71,6 +72,12 @@ Configuration is deployment state:
 The Node Provider must configure the same model, device, compute, batch size, service version and
 WhisperX version. A mismatch fails before transcription results are accepted.
 
+The service logs ASR loading, transcription, language-model loading and word alignment where those
+operations run. Completion entries include elapsed times. A loading entry means the library call
+has begun and may include a weight download; the download client supplies any transfer progress.
+Transcripts and audio content are not included in these service progress entries. `/health` answers
+after ASR loading, so a healthy service may still prepare a language model on its first request.
+
 ## Package preparation
 
 Local package preparation includes `src/**/*.py` in uv's package cache inputs. Updating service code