@hypit/hypit 0.1.13 → 0.2.0

package/packages/provider-hyperframes-local/src/program.ts

@@ -1,54 +1,46 @@
-import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 
 import { probeMediaToolchain } from "@hypit/media-execution";
 import type { ManagedProgram, ManagedProgramState } from "@hypit/runtime-kit";
-
-function run(executable: string, args: readonly string[]): Promise<{ ok: boolean; output: string }> {
-  return new Promise((resolve) => {
-    execFile(executable, [...args], { timeout: 15_000, shell: false, windowsHide: true }, (error, stdout, stderr) => {
-      resolve(error === null
-        ? { ok: true, output: stdout.trim() }
-        : { ok: false, output: (stderr.trim() || error.message).split("\n").at(-1) ?? "" });
-    });
-  });
-}
+import { browserCacheDirectory, browserDownloadBaseUrl, browserDownloadUrl, browserExecutablePath, configuredBrowserPath, requireBrowserExecutable, selectedBrowserVersion } from "./browser.js";
+import type { BrowserOptions } from "./browser.js";
 
 /**
- * HyperFrames owns the browser cache behind its CLI. It is deployment state,
- * not an author dependency, so the Endpoint lifecycle prepares it only
- * when this Provider is selected.
+ * This Provider owns browser selection and preparation. Probes never install;
+ * rendering receives the same selected executable instead of invoking engine discovery.
  */
 export function localHyperframesBrowserProgram(
-  input: {
+  input: BrowserOptions & {
     readonly id: string;
     readonly nodePath: string;
-    readonly hyperframesCliPath: string | (() => string);
     readonly ffprobePath: string;
     readonly ffmpegPath?: string;
   },
 ): ManagedProgram {
-  const cliPath = () => typeof input.hyperframesCliPath === "string" ? input.hyperframesCliPath : input.hyperframesCliPath();
+  const version = selectedBrowserVersion(input);
+  const selectedPath = browserExecutablePath(input);
+  const baseUrl = browserDownloadBaseUrl(input);
   const probeBrowser = async (): Promise<ManagedProgramState> => {
-    let executable: string;
-    try { executable = cliPath(); } catch (error) { return { state: "down", detail: error instanceof Error ? error.message : String(error) }; }
-    const located = await run(input.nodePath, [executable, "browser", "path"]);
-    if (!located.ok) return { state: "down", detail: `HyperFrames browser is unavailable: ${located.output}` };
-    const path = located.output.trim();
-    if (path.length === 0 || path.includes("\n") || path.includes("\r")) {
-      return { state: "mismatch", detail: "HyperFrames returned an invalid browser path" };
-    }
-    const version = await run(path, ["--version"]);
-    if (!version.ok || version.output.length === 0) {
-      return { state: "mismatch", detail: `HyperFrames browser cannot start: ${version.output}` };
-    }
+    try { await requireBrowserExecutable(selectedPath, version); }
+    catch (error) { return { state: "down", detail: error instanceof Error ? error.message : String(error) }; }
     return { state: "ready" };
   };
   return {
     id: input.id,
-    installation: {
-      probe: probeBrowser,
-      get commands() { return [{ command: input.nodePath, args: [cliPath(), "browser", "ensure"] }]; },
-    },
+    ...(configuredBrowserPath(input) === undefined ? {
+      // Projects sharing this installation also share the existing Program lifecycle lock/logs.
+      stateRoot: join(browserCacheDirectory(input), ".hypit-render-program"),
+      installation: {
+        probe: probeBrowser,
+        commands: [{ label: `Install Chrome Headless Shell ${version} at ${selectedPath} from ${browserDownloadUrl(input)}`, command: input.nodePath, args: [
+          "--import", import.meta.resolve("tsx"),
+          "--import", new URL("./capture-bootstrap.ts", import.meta.url).href,
+          fileURLToPath(new URL("./browser-install.ts", import.meta.url)), browserCacheDirectory(input), version!,
+          ...(baseUrl === undefined ? [] : [baseUrl]),
+        ] }],
+      },
+    } : {}),
     async probe(): Promise<ManagedProgramState> {
       const browser = await probeBrowser();
       if (browser.state !== "ready") return browser;

package/packages/provider-hyperframes-local/src/provider.ts

@@ -2,7 +2,6 @@ import { defineEndpointPackage } from "@hypit/endpoint-kit";
 import { mediaTypes } from "@hypit/media";
 import { renderHyperframesCapabilities, verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
 import { canonicalize } from "@hypit/protocol";
-import { resolveNodePackageExecutable } from "@hypit/package-loader-node";
 import { renderHyperframesVisual, resolveExecutionOptions, renderWorkerLimit } from "./render.js";
 import type { HyperframesExecutionOptions } from "./options.js";
 import { renderProgressReporter } from "./progress.js";
@@ -14,17 +13,12 @@ export type CreateLocalHyperframesProviderOptions = HyperframesExecutionOptions
   readonly pool?: string;
   /** Used by managed browser installation, not frame capture. */
   readonly nodePath?: string;
-  readonly hyperframesCliPath?: string;
   /** Whole render requests admitted concurrently; independent of frame workers. */
   readonly defaultConcurrency?: number;
   /** Shared Chrome slots across Need executions using this pool. */
   readonly browserCapacity?: number;
 };
 
-export function defaultHyperframesCliPath(): string {
-  return resolveNodePackageExecutable("hyperframes", "hyperframes", { from: import.meta.url });
-}
-
 export function createLocalHyperframesProvider(config: CreateLocalHyperframesProviderOptions) {
   const execution = resolveExecutionOptions(config);
   const pool = config.pool ?? config.instance ?? "hyperframes.local";
@@ -62,7 +56,10 @@ export function createLocalHyperframesProvider(config: CreateLocalHyperframesPro
           : request.range.endFrameExclusive - request.range.startFrame;
         const progress = renderProgressReporter(context.reportProgress, frameCount);
         try {
-          const visual = await renderHyperframesVisual(request, { ...config, workers: execution.workers, maxWorkers,
+          const visual = await renderHyperframesVisual(request, { ...config,
+            ...(execution.chromePath === undefined ? { browserVersion: execution.browserVersion! } : { chromePath: execution.chromePath }),
+            browserCacheDirectory: execution.browserCacheDirectory,
+            workers: execution.workers, maxWorkers,
             resources: context.resources, onProgress: progress.onProgress,
             ...(context.reportDiagnostic === undefined ? {} : { onDiagnostic: context.reportDiagnostic }) });
           return { value: { kind: "inline", value: canonicalize(visual) } };

package/packages/provider-hyperframes-local/src/render.ts

@@ -6,7 +6,7 @@ import type { EndpointInvocationContext } from "@hypit/endpoint-kit";
 import { stageHyperframesProject } from "@hypit/hyperframes/project";
 import { sealRenderedVisual } from "@hypit/media";
 import type { MediaFrameRange, RenderedVisual } from "@hypit/media";
-import { verifyCompositableSurfaceBytes } from "@hypit/media-execution";
+import { verifyCompositableSurfaceFile } from "@hypit/media-execution";
 import { verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
 import type { HyperframesVisualRequest } from "@hypit/render-hyperframes";
 import { isStreamingResourceStore } from "@hypit/runtime";
@@ -15,6 +15,7 @@ import { assert, positiveInteger } from "./process.js";
 import { runCaptureProcess } from "./capture-process.js";
 import { finished } from "node:stream/promises";
 import { autoWorkerLimit } from "./concurrency.js";
+import { browserCacheDirectory, browserExecutablePath, configuredBrowserPath, requireBrowserExecutable, selectedBrowserVersion } from "./browser.js";
 
 export type HyperframesRenderProgress =
   | { readonly phase: "staging" | "encoding" | "storing"; readonly elapsedMs: number }
@@ -43,6 +44,9 @@ export function resolveExecutionOptions(options: HyperframesExecutionOptions) {
   const browserGpu = options.browserGpu ?? "hardware";
   assert(["auto", "software", "hardware"].includes(browserGpu), "HyperFrames browserGpu is invalid");
   return {
+    chromePath: configuredBrowserPath(options),
+    browserVersion: selectedBrowserVersion(options),
+    browserCacheDirectory: browserCacheDirectory(options),
     workers,
     maxWorkers: workers === "auto" ? positiveInteger(options.maxWorkers ?? autoWorkerLimit(), "maxWorkers") : workers,
     quality, browserGpu,
@@ -71,7 +75,7 @@ export async function renderHyperframesVisual(
   options: RenderHyperframesVisualOptions,
 ): Promise<RenderedVisual> {
   verifyHyperframesVisualRequest(request);
-  const config = resolveExecutionOptions(options);
+  const config = { ...resolveExecutionOptions(options), chromePath: browserExecutablePath(options) };
   const { document } = request;
   const range = request.range ?? { startFrame: 0, endFrameExclusive: document.frameCount };
   const frameCount = range.endFrameExclusive - range.startFrame;
@@ -97,8 +101,9 @@ export async function renderHyperframesVisual(
   };
   try {
     signal.throwIfAborted();
+    await requireBrowserExecutable(config.chromePath, config.browserVersion);
     await options.onDiagnostic?.({ level: "info", message:
-      `Render ${frameCount} frames; workers ${config.workers} (limit ${renderWorkerLimit(config, frameCount, document.frameRate.numerator / document.frameRate.denominator)}); opaque fast PNG; quality ${config.quality}; GPU ${config.browserGpu}; encoder ${config.ffmpegPath}` });
+      `Render ${frameCount} frames; workers ${config.workers} (limit ${renderWorkerLimit(config, frameCount, document.frameRate.numerator / document.frameRate.denominator)}); opaque fast PNG; quality ${config.quality}; GPU ${config.browserGpu}; browser ${config.chromePath}; encoder ${config.ffmpegPath}` });
     options.onProgress?.({ phase: "staging", elapsedMs: 0 });
     work = await mkdtemp(join(tmpdir(), "hypit-hyperframes-local-"));
     await stageHyperframesProject({ document, directory: work, signal,
@@ -109,7 +114,7 @@ export async function renderHyperframesVisual(
         assert(bytes !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
         return bytes;
       },
-      validateSurface: (surface, bytes, probeSignal) => verifyCompositableSurfaceBytes({ surface, bytes,
+      validateSurface: (surface, path, probeSignal) => verifyCompositableSurfaceFile({ surface, path,
         ffprobePath: config.ffprobePath, processTimeoutMs: config.processTimeoutMs,
         maxProbeOutputBytes: config.maxProcessOutputBytes, signal: probeSignal! }),
     });

package/packages/provider-whisperx-local/README.md

@@ -43,7 +43,8 @@ For multilingual transcription with quality as the priority and suitable hardwar
     "expectedModel": "large-v3",
     "expectedDevice": "cuda",
     "expectedCompute": "float16",
-    "expectedBatchSize": 4
+    "expectedBatchSize": 4,
+    "alignmentLanguages": ["zh", "en"]
   }
 }
 ```
@@ -57,7 +58,11 @@ or hosted service for the actual language, material and time available rather th
 successively larger models as a routine sequence.
 
 `expectedModel` selects speech recognition. WhisperX separately loads the language-specific
-alignment model when that language is first requested. A larger ASR model can improve the words
+alignment model from prepared local resources when that language is first requested. Set
+`alignmentLanguages` to the language codes needed by this production before preparation. This is a
+preparation demand, not a central language whitelist; already cached supported languages remain usable.
+Omission prepares only ASR and sentence data, and does not imply every alignment model is installed.
+A larger ASR model can improve the words
 fed into alignment, but does not select a larger aligner or guarantee better timing by itself.
 The health response identifies the loaded ASR configuration; it does not establish that every
 language's alignment weights are cached. See [WhisperX usage](https://github.com/m-bain/whisperX#usage-)
@@ -65,8 +70,9 @@ and [faster-whisper deployment](https://github.com/SYSTRAN/faster-whisper#usage)
 
 ## Preparation and downloads
 
-The Runtime installs and starts the packaged service in the machine Program Home when this Endpoint
-is selected. The environment is reused across projects and sessions. The current local package and
+An explicit `programs up` or `runtime up` prepares and starts the selected packaged service in the
+machine Program Home. Selecting an Endpoint alone does not install it. The environment is reused
+across projects and sessions. The current local package and
 service are trusted code; this is not a community-plugin sandbox.
 
 `hypit paths` reports the machine `hostState`. The managed installation lives below
@@ -75,21 +81,31 @@ service are trusted code; this is not a community-plugin sandbox.
 the service host includes its port. The default service is `http://127.0.0.1:8765` and exposes
 its configuration through `/health`. Inspect an existing Profile's address and expected settings
 when locating that service. A custom `serviceCommand` supplies its own installation and start command.
-`hypit programs status` checks the Programs selected by the supplied Profile; `programs up` prepares
-and starts them. The managed installation does not require a global `whisperx` shell command.
+`hypit programs prepare --endpoint <instance>` prepares the configured ASR model, requested alignment
+models and sentence data without starting a process. It also works when the service is already online.
+`programs up` prepares and starts the selected Programs; `programs status` reports process readiness.
+Adding a language requires preparation, not a service restart, when its cache location is unchanged.
+`modelCacheDirectory` optionally selects a root with `huggingface/` and `torch/` subdirectories;
+relative paths resolve against the Runtime data root. Omission retains the upstream Hugging Face and
+torch caches and their environment settings. Changing a running service's cache selection requires
+an explicit restart when idle, just like changing its model or hardware. The managed installation
+does not require a global `whisperx` shell command.
 
 Preparation and service processes inherit the environment of the command starting them. Set
 network and cache variables there before `programs up` or `runtime up`. A service already running
 retains its earlier environment. Inspect its reported log before deciding whether a selected
 Program needs restarting, and account for active work using it.
 
+If NLTK refuses a proxied fetch during preparation, follow the service’s
+[explicit proxy preparation](../../services/whisperx/README.md#preparing-sentence-data-through-a-proxy).
+
 Preparation commands write `install.log`; the running service writes `program.log`, with stderr in
 `program.err.log` on Windows. Inspect the stderr file for Python model-loading and download messages.
 `programs status` reports these files as `installationLogPath`, `logPath` and `errorLogPath` when they
-exist, even before installation finishes. Preparation notices name the Python environment and NLTK
-commands separately. The service logs the start and completion of ASR loading, transcription,
-language-alignment model loading and alignment, with elapsed times. Loading may include a download;
-transfer details come from the underlying client, not an estimated percentage from the Provider.
+exist, even before installation finishes. Preparation notices name the Python environment and selected model/language resources separately. The service logs the start and completion of ASR loading, transcription,
+language-alignment model loading and alignment, with elapsed times. Downloads happen only in
+preparation; startup and inference only load local resources. A missing resource fails with a
+preparation instruction. Transfer details come from the underlying client during preparation.
 The service health endpoint becomes available after ASR loading. A startup readiness wait expiring
 can leave that process still loading. Its PID is recorded when spawned; repeated `up` observes it,
 and `programs down` can stop it during loading. PID liveness and service readiness are separate facts.

package/packages/provider-whisperx-local/src/activation.ts

@@ -1,3 +1,4 @@
+import { resolve } from "node:path";
 import {
   createRuntimeEndpointAdapterFacet,
   runtimeConfigExact,
@@ -18,7 +19,7 @@ const localWhisperXRuntimeAdapter = createRuntimeEndpointAdapterFacet({
       "baseUrl", "expectedModel", "expectedDevice", "expectedCompute", "expectedBatchSize",
       "expectedServiceVersion", "expectedWhisperXVersion",
       "defaultConcurrency", "requestTimeoutMs", "maxResponseBytes",
-      "serviceCommand",
+      "serviceCommand", "alignmentLanguages", "modelCacheDirectory",
     ], "local WhisperX");
     const baseUrl = runtimeConfigString(config.baseUrl, "WhisperX baseUrl");
     if (baseUrl !== undefined) {
@@ -37,6 +38,12 @@ const localWhisperXRuntimeAdapter = createRuntimeEndpointAdapterFacet({
     const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "WhisperX defaultConcurrency");
     const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "WhisperX requestTimeoutMs");
     const maxResponseBytes = runtimeConfigPositiveInteger(config.maxResponseBytes, "WhisperX maxResponseBytes");
+    const modelCacheDirectory = runtimeConfigString(config.modelCacheDirectory, "WhisperX modelCacheDirectory");
+    const alignmentLanguages = config.alignmentLanguages;
+    if (alignmentLanguages !== undefined && (!Array.isArray(alignmentLanguages)
+      || alignmentLanguages.some((item) => typeof item !== "string" || !/^[a-z]+$/u.test(item)))) {
+      throw new Error("WhisperX alignmentLanguages must be an array of lowercase language codes");
+    }
     const serviceCommandValue = config.serviceCommand;
     if (serviceCommandValue !== undefined
       && (!Array.isArray(serviceCommandValue) || serviceCommandValue.length === 0
@@ -80,6 +87,8 @@ const localWhisperXRuntimeAdapter = createRuntimeEndpointAdapterFacet({
         expectedServiceVersion: selectedServiceVersion,
         expectedWhisperXVersion: selectedWhisperXVersion,
         ...(serviceCommand === undefined ? {} : { serviceCommand }),
+        ...(alignmentLanguages === undefined ? {} : { alignmentLanguages: alignmentLanguages as string[] }),
+        ...(modelCacheDirectory === undefined ? {} : { modelCacheDirectory: resolve(context.dataRoot, modelCacheDirectory) }),
       }),
     };
   },

package/packages/provider-whisperx-local/src/program.ts

@@ -52,6 +52,8 @@ export type LocalWhisperXProgramOptions = {
   readonly expectedServiceVersion: string;
   readonly expectedWhisperXVersion: string;
   readonly serviceCommand?: ManagedProgramCommand;
+  readonly alignmentLanguages?: readonly string[];
+  readonly modelCacheDirectory?: string;
 };
 
 export function localWhisperXProgram(options: LocalWhisperXProgramOptions): ManagedProgram {
@@ -85,11 +87,13 @@ export function localWhisperXProgram(options: LocalWhisperXProgramOptions): Mana
     HYPIT_WHISPERX_COMPUTE: expected.compute,
     HYPIT_WHISPERX_BATCH_SIZE: String(expected.batchSize),
     HYPIT_WHISPERX_NLTK_DATA: nltkData,
+    ...(options.modelCacheDirectory === undefined ? {} : { HYPIT_WHISPERX_MODEL_CACHE: options.modelCacheDirectory }),
+    HYPIT_WHISPERX_ALIGNMENT_LANGUAGES: (options.alignmentLanguages ?? []).join(" "),
   };
   const check: ManagedProgramCommand = {
     command: pythonEnvironmentCommand(environment, "hypit-whisperx-check"),
-    args: [],
-    env: { HYPIT_WHISPERX_NLTK_DATA: nltkData },
+    args: ["--models"],
+    env: serviceEnvironment,
   };
   const managedStart: ManagedProgramCommand = {
     command: pythonEnvironmentCommand(environment, "hypit-whisperx-service"),
@@ -131,10 +135,10 @@ export function localWhisperXProgram(options: LocalWhisperXProgramOptions): Mana
           args: ["sync", "--project", localWhisperXManagedProject, "--frozen", "--no-editable"],
           env: { UV_PROJECT_ENVIRONMENT: environment },
         }, {
-          label: "Prepare NLTK sentence data",
+          label: `Prepare WhisperX ${expected.model} and alignment resources for ${(options.alignmentLanguages ?? []).join(", ") || "no selected languages"}`,
           command: pythonEnvironmentCommand(environment, "hypit-whisperx-prepare"),
           args: ["--nltk-data", nltkData],
-          env: { HYPIT_WHISPERX_NLTK_DATA: nltkData },
+          env: serviceEnvironment,
         }],
       },
     } : {}),

package/packages/runtime-host-node/README.md

@@ -53,3 +53,8 @@ to start execution, then `const runtime = await host.createRuntime(); await runt
 to submit work. `RuntimeHostExecution` does not run a second embedded Worker loop. A local carrier
 may stop accepting new Builds and drain; its assigned Builds stay in place and all carriers continue
 using the same resource accounting. Process policy belongs to the local Runtime, not this Host ABI.
+
+`prepareHostPackages` accepts exact specifier strings or `{ specifier, env }` installation inputs.
+The optional environment is applied only to that npm child process, merged over its inherited
+environment. It is neither persisted as installation status nor returned in package reports.
+The shared installer does not interpret SDK-specific variables; their owning packages supply them.

package/packages/runtime-host-node/src/index.ts

@@ -70,17 +70,20 @@ export type BuildView = {
   }[];
 };
 
-export type RuntimeHostCredentialStatus = {
+export type RuntimeHostCredentialDescription = {
   readonly endpoint: string;
   readonly slot: string;
   readonly label: string;
   readonly kind: "secret" | "json";
   readonly ref: CredentialRef;
   readonly acquisition?: CredentialAcquisition;
-  readonly configured: boolean;
   readonly writable: boolean;
 };
 
+export type RuntimeHostCredentialStatus = RuntimeHostCredentialDescription & {
+  readonly configured: boolean;
+};
+
 export type RuntimeHostControl = {
   /** Build evidence while active. Finished evidence is read through its Result Repository. */
   logs?(build: string, lines: number): Promise<import("@hypit/runtime").ExecutionLogView | undefined>;
@@ -105,6 +108,8 @@ export type RuntimeHostResultControl = {
 };
 
 export type RuntimeHostCredentialControl = {
+  /** Endpoint declarations and Store write capability; never reads an existing secret. */
+  describeCredentials(endpoint?: string): Promise<readonly RuntimeHostCredentialDescription[]>;
   credentials(endpoint?: string): Promise<readonly RuntimeHostCredentialStatus[]>;
   putCredential(endpoint: string, slot: string, secret: string): Promise<RuntimeHostCredentialStatus>;
   deleteCredential(endpoint: string, slot: string): Promise<{
@@ -240,6 +245,7 @@ export type RuntimeController = {
     down(options?: { readonly maxWaitMs?: number }): Promise<RuntimeWorkerState>;
   };
   readonly programs: {
+    prepare(options?: { readonly endpoints?: readonly string[]; readonly onProgress?: (event: ManagedProgramProgress) => void }): Promise<{ readonly dataRoot: string; readonly programs: readonly ManagedProgramReport[] }>;
     up(options: {
       readonly maxWaitMs?: number;
       readonly onProgress?: (event: ManagedProgramProgress) => void;

package/packages/runtime-host-node/src/packages.ts

@@ -73,7 +73,7 @@ export async function inspectHostPackage(
     : undefined;
 }
 
-async function runNpm(root: string, specifiers: readonly string[], logPath: string): Promise<void> {
+async function runNpm(root: string, specifiers: readonly string[], logPath: string, env?: Readonly<Record<string, string>>): Promise<void> {
   // npm's prefix and cwd must denote the same physical project (not /tmp vs /private/tmp).
   const cwd = await realpath(root);
   const npmArgs = [
@@ -96,6 +96,7 @@ async function runNpm(root: string, specifiers: readonly string[], logPath: stri
         cwd,
         shell: false,
         windowsHide: true,
+        env: { ...process.env, ...env },
         stdio: ["ignore", log.fd, log.fd],
       });
       child.on("error", (error) => reject(new Error(`Cannot start npm: ${error.message}. Log: ${logPath}`, { cause: error })));
@@ -114,21 +115,26 @@ async function runNpm(root: string, specifiers: readonly string[], logPath: stri
  * package.json, lockfile and dependencies; Hypit keeps no parallel inventory.
  */
 export async function prepareHostPackages(
-  specifiers: readonly string[],
+  specifiers: readonly (string | { readonly specifier: string; readonly env?: Readonly<Record<string, string>> })[],
   options: {
     readonly root: string;
     readonly onProgress?: (event: HostPackageProgress) => void;
   },
 ): Promise<readonly HostPackageReport[]> {
   const root = resolve(options.root);
-  const bySpecifier = new Map<string, RegistryPackageSpec>();
+  const bySpecifier = new Map<string, RegistryPackageSpec & { readonly env?: Readonly<Record<string, string>> }>();
   for (const specifier of specifiers) {
-    const parsed = parseRegistryPackageSpec(specifier);
-    bySpecifier.set(parsed.specifier, parsed);
+    const parsed = parseRegistryPackageSpec(typeof specifier === "string" ? specifier : specifier.specifier);
+    const env = { ...bySpecifier.get(parsed.specifier)?.env };
+    for (const [key, value] of Object.entries(typeof specifier === "string" ? {} : specifier.env ?? {})) {
+      if (env[key] !== undefined && env[key] !== value) throw new Error(`Conflicting installation environment ${key} for ${parsed.specifier}`);
+      env[key] = value;
+    }
+    bySpecifier.set(parsed.specifier, { ...parsed, ...(Object.keys(env).length === 0 ? {} : { env }) });
   }
   const required = [...bySpecifier.values()].sort((left, right) => left.specifier.localeCompare(right.specifier));
   const reports: HostPackageReport[] = [];
-  for (const item of required) {
+  for (const { env, ...item } of required) {
     const installation = externalPackageInstallRoot(root, item.name, item.version);
     options.onProgress?.({ ...item, phase: "checking" });
     const missing = await installedVersion(installation, item.name) !== item.version;
@@ -142,7 +148,7 @@ export async function prepareHostPackages(
         dependencies: { [item.name]: item.version },
       }, null, 2)}\n`, "utf8");
       options.onProgress?.({ ...item, phase: "installing", logPath });
-      await runNpm(installation, [item.specifier], logPath);
+      await runNpm(installation, [item.specifier], logPath, env);
     }
     const version = await installedVersion(installation, item.name);
     if (version !== item.version) {

package/packages/runtime-kit/README.md

@@ -43,8 +43,12 @@ video package by name.
 
 `ManagedProgram.installation.prepareBeforeStart` lets a Provider reconcile its installed environment
 before a cold start, even when the installation probe already passes. The declared commands use the
-Provider's ordinary package manager. A healthy running Program is reused before this preparation is
-considered; Runtime does not inspect source files or infer implementation versions.
+Provider's ordinary package manager. `programs prepare` runs the declared installation independently
+of process startup; `programs up` also checks its resources when the process is already healthy.
+The installation probe covers the owner's selected execution resources, while the process probe
+reports service readiness. Cold reconciliation still applies only before starting a new process.
+Runtime does not name models, inspect source files or infer implementation versions. Preparation
+may acquire resources; execution must consume already prepared resources and report what is missing.
 `ManagedProgramCommand.label` optionally names a command's purpose for progress and log headings.
 It is display text supplied by the Program owner, not a phase to persist or interpret. Runtime
 reports generic process/probe facts; the service itself owns domain-specific progress in its logs.

package/packages/runtime-kit/src/index.ts

@@ -42,11 +42,11 @@ export type ManagedProgramCommand = {
 };
 
 export type ManagedProgramInstallation = {
-  /** Truthful inspection of the installed program; no installer-owned receipt. */
+  /** Read-only inspection of the selected environment and resources; no downloads or receipts. */
   probe(): Promise<ManagedProgramState>;
   /** Reconcile an installed environment before a cold start, using its package manager's cache. */
   readonly prepareBeforeStart?: boolean;
-  /** Commands run when installation is missing, or before a cold start when requested above. */
+  /** Explicit preparation commands, run for missing resources or cold reconciliation above. */
   readonly commands: readonly ManagedProgramCommand[];
 };
 

package/packages/runtime-local/README.md

@@ -242,7 +242,12 @@ controller returned by `await host.controller()`, and calls `build(...)` on the
 `await host.createRuntime()`. There is one production process-lifecycle path.
 
 Managed Programs have independent lifetimes. A healthy WhisperX service keeps its model loaded;
-`prepareBeforeStart` reconciles a cold installation through uv's source-aware synchronization.
+`programs prepare --endpoint <instance>` prepares selected resources without starting or stopping
+that service. Its installation probe is independent of process health, so an online service does not
+hide a newly requested language model. `programs up` prepares missing resources and starts the service
+if needed. `prepareBeforeStart` additionally reconciles a cold installation through the package
+manager's source-aware synchronization. The Provider owns the resource choices and commands;
+Runtime only invokes them under the existing lifecycle lock.
 `runtime down` stops the coordinator and asks its executors to stop; Programs are stopped separately.
 Distribution changes and shell environment changes still concern the coordinator's bootstrap process.
 Inspect active work before restarting it. Environment-backed credentials use that inherited process
@@ -258,3 +263,13 @@ capacity release and every completed Result. They use the production execution p
 This is a load experiment rather than part of every package regression. It reports fixture preparation,
 local progress, completion, executor RSS and cleanup separately; total test time also includes creating
 and removing the temporary Result repositories. Neither suite uses a completion-time performance target.
+
+
+### Credential management without reading the old value
+
+`openCredentials(endpoint)` opens only the selected Endpoint's credential control.
+`describeCredentials(endpoint)` returns its declared slots and each Store's write capability without
+resolving secrets. `credentials(endpoint)` also reads current values to report status and propagates
+read failures. Login and logout use the former: a damaged old credential cannot prevent replacement
+or deletion. Successful writes and deletions report their operation's result without rereading the
+secret. Execution still resolves credentials normally and reports Store errors.

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

@@ -462,7 +462,7 @@ export async function prepareRuntimeConfigPackages(
     ...document.endpoints.map((item) => item.use),
     ...credentials.credentials.map((item) => item.use),
   ], options.distributionPackageRoot);
-  return await prepareHostPackages(requirements.map((item) => item.specifier), {
+  return await prepareHostPackages(requirements, {
     root: hypitHostPackageRoot(options.hostStateRoot),
     ...(options.onProgress === undefined ? {} : { onProgress: options.onProgress }),
   });

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

@@ -28,16 +28,21 @@ export function createLocalCredentialControl(
       : `Endpoint ${endpoint} repeats credential slot ${slot}`);
     return matches[0]!;
   };
-  const status = async (item: typeof descriptions[number]) => ({
+  const describe = async (item: typeof descriptions[number]) => ({
     ...structuredClone(item),
-    configured: await options.credentialStore.resolve(item.ref) !== undefined,
     writable: await writableCredentialStore(options.credentialStore, item.ref) !== undefined,
   });
 
   return {
+    async describeCredentials(endpoint) {
+      return await Promise.all(descriptions.filter((item) => endpoint === undefined || item.endpoint === endpoint).map(describe));
+    },
     async credentials(endpoint) {
       const selected = descriptions.filter((item) => endpoint === undefined || item.endpoint === endpoint);
-      return await Promise.all(selected.map(status));
+      return await Promise.all(selected.map(async (item) => ({
+        ...await describe(item),
+        configured: await options.credentialStore.resolve(item.ref) !== undefined,
+      })));
     },
     async putCredential(endpoint, slot, secret) {
       assert(secret.length > 0, "credential secret is empty");
@@ -45,14 +50,14 @@ export function createLocalCredentialControl(
       const store = await writableCredentialStore(options.credentialStore, item.ref);
       assert(store !== undefined, `CredentialStore ${item.ref.store} is not writable`);
       await store.put(item.ref, { secret });
-      return await status(item);
+      return { ...structuredClone(item), writable: true, configured: true };
     },
     async deleteCredential(endpoint, slot) {
       const item = credential(endpoint, slot);
       const store = await writableCredentialStore(options.credentialStore, item.ref);
       assert(store !== undefined, `CredentialStore ${item.ref.store} is not writable`);
       const deleted = await store.delete(item.ref);
-      return { deleted, credential: await status(item) };
+      return { deleted, credential: { ...structuredClone(item), writable: true, configured: false } };
     },
     close() {
       return options.close?.();

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

@@ -23,6 +23,7 @@ import {
 } from "./config.js";
 import {
   bringManagedProgramsUp,
+  prepareManagedPrograms,
   reportManagedPrograms,
   takeManagedProgramsDown,
 } from "./programs.js";
@@ -82,6 +83,7 @@ export async function openLocalRuntimeHost(
         ),
       },
       programs: {
+        prepare: async (programOptions) => await prepareManagedPrograms(profile, { ...programOptions, packageRoot, ...distribution }),
         up: async (programOptions) => await bringManagedProgramsUp(profile, { ...programOptions, packageRoot, ...distribution }),
         down: async (scope) => await takeManagedProgramsDown(profile, { ...scope, packageRoot, ...distribution }),
         report: async (scope) => await reportManagedPrograms(profile, { ...scope, packageRoot, ...distribution }),

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

@@ -28,6 +28,7 @@ export {
 } from "./config.js";
 export {
   bringManagedProgramsUp,
+  prepareManagedPrograms,
   reportManagedPrograms,
   takeManagedProgramsDown,
 } from "./programs.js";