@hypit/hypit 0.1.7 → 0.1.9

package/README.md

@@ -38,7 +38,7 @@
 
 Hypit gives AI agents (Claude Code, Codex...) a language and system to create video. Drop in a video, and your agent clones it as a complete workflow: footage, captions, B-roll and effects, all anchored to words instead of seconds.
 
-**To be clear:** cloning a video is the fastest way in, not the only one. You can start from our templates, or just describe the video you want and your agent writes the workflow from scratch. Generation models are optional too: a workflow can compile captions, motion graphics and code-rendered visuals into a finished video without calling a single model, so a video can cost exactly $0.
+**To be clear:** cloning a video is the fastest way in, not the only one. You can start from our templates, or just describe the video you want and your agent writes the workflow from scratch. Generation models are optional too: a workflow can compile captions, motion graphics and code-rendered visuals into a finished video without calling a generation model or incurring its service charges.
 
 ![SVML source and live video preview](https://storage.googleapis.com/hypit-public-assets/showcase/npm/2026-09-10/demo-compact.gif)
 
@@ -61,6 +61,13 @@ npx skills add hypit-ai/hypit -g
 This installs the Skill. On first use, your agent checks for the Hypit executable and helps prepare
 it if needed. Your video project can live anywhere.
 
+Hypit is free to use; your Coding Agent and model services have their own accounts and charges.
+HypiHub is our recommended hosted model service. You can also use your own API or local models;
+tell your agent the service name and API documentation so it can set up the appropriate connection.
+
+[Agent environments and entry partners](https://github.com/hypit-ai/hypit/blob/main/docs/guide/agents.md) ·
+[Model and deployment services](https://github.com/hypit-ai/hypit/blob/main/docs/guide/service-partners.md)
+
 [Watch the complete video examples on GitHub](https://github.com/hypit-ai/hypit#examples).
 
 ## Use the Hypit skill
@@ -85,9 +92,9 @@ Your agent can check the environment, request the credentials the video needs, g
 ## Why Hypit
 
 - **Clone any video:** drop in a video, get the whole workflow — footage, captions, B-roll, effects. Not a script breakdown.
-- **One workflow, 100 variants:** the second video costs almost nothing; the hundredth is a loop.
+- **One workflow, 100 variants:** reuse the composition and existing material; generate the parts that change.
 - **Pluggable components:** swap the host without touching the captions. Use the library, fork it, or write your own.
-- **Open source, $0:** no seat pricing, no per-render fees, no watermark. Arcads charges $220/mo, Creatify $39, before you render anything — but Hypit is $0.
+- **Open source:** no Hypit seat pricing, per-render fees or added watermark. Model-service usage is billed by the service you choose.
 
 ## What Hypit Can Build
 
@@ -98,7 +105,7 @@ Drop in a video and your agent clones the whole workflow — or describe what yo
 - **TikTok Shop and affiliate videos** — one format that converts, a new SKU every day. Swap the product, the price, the CTA; the structure that worked stays untouched.
 - **AI UGC and talking heads** — narration, word-level captions, B-roll, comment stickers, beat-synced cuts, all wired automatically.
 - **Podcast and interview clips** — split-screen layouts, speaker-aware captions, reaction overlays.
-- **Code-rendered videos** — visuals driven entirely by front-end code. Compiled from source, zero API calls, 0 dollars a video.
+- **Code-rendered videos** — visuals driven entirely by front-end code, rendered locally without generation API calls.
 - **Localized versions** — the same video in ten languages. Rewrite a line and the timing re-flows itself.
 
 ## Stay Tuned with Us
@@ -137,6 +144,10 @@ commands and the repository layout.
   </tr>
 </table>
 
+## ⭐ Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=hypit-ai/hypit&type=Date)](https://www.star-history.com/#hypit-ai/hypit&Date)
+
 ## License
 
 Hypit is released under the [Hypit Open Source License](https://github.com/hypit-ai/hypit/blob/main/LICENSE). The videos and other outputs you create belong to you; third-party models and services may have their own terms.

package/dist/public/endpoint-kit.d.ts

@@ -187,7 +187,7 @@ type EndpointInvocationContext = {
     readonly credentials: Readonly<Record<string, EndpointCredential>>;
     /** Explicit non-secret diagnostic output. The Provider owns its content, never its storage. */
     readonly reportDiagnostic?: (diagnostic: ExecutionDiagnostic) => Promise<void>;
-    /** Report non-secret activity of a long local call without creating a remote Operation. */
+    /** Report non-secret activity while an immediate call or asynchronous action is still running. */
     readonly reportProgress?: (progress: OperationProgress) => Promise<void>;
 };
 type ImmediateEndpointHandler = (context: EndpointInvocationContext) => Awaitable<EndpointFulfillment>;

package/dist/public/runtime-kit.d.ts

@@ -185,7 +185,7 @@ type EndpointInvocationContext = {
     readonly credentials: Readonly<Record<string, EndpointCredential>>;
     /** Explicit non-secret diagnostic output. The Provider owns its content, never its storage. */
     readonly reportDiagnostic?: (diagnostic: ExecutionDiagnostic) => Promise<void>;
-    /** Report non-secret activity of a long local call without creating a remote Operation. */
+    /** Report non-secret activity while an immediate call or asynchronous action is still running. */
     readonly reportProgress?: (progress: OperationProgress) => Promise<void>;
 };
 type ImmediateEndpointHandler = (context: EndpointInvocationContext) => Awaitable<EndpointFulfillment>;
@@ -350,6 +350,8 @@ type RuntimeDoctorDiagnostic = {
     readonly subject?: string;
 };
 type ManagedProgramCommand = {
+    /** Optional human-readable purpose, supplied by the program owner. Not a lifecycle state. */
+    readonly label?: string;
     readonly command: string;
     readonly args: readonly string[];
     readonly cwd?: string;

package/examples/provider-package/README.md

@@ -23,6 +23,18 @@ The example service uses Bearer authentication for these API operations:
 | Read rates | `GET /rates?model=gpt-image-2` → service-owned fields and a `description` stating rates, units and conditions |
 | Collect result | GET the signed image URL without the account key |
 
+HTTP failures expose a public `{ "error": { "code": "…", "message": "…" } }` and optional
+`X-Request-Id`; failed tasks carry the same `error` object. The Provider preserves these fields,
+the failed API operation or task ID, and omits unrelated response fields and signed URLs.
+This example schema is not a universal service-error format: adapt the interpretation to the chosen API.
+
+Known request limits and model identity are resolved before the media URL resolver can upload.
+This service exposes no model-catalogue endpoint, so the example invents none. Services with a
+documented query can use it before transferring references. Request preparation, submission and
+collection report live activity through `reportProgress`; queued/running task responses supply
+pending progress between calls. The Provider follows the selected mapping without substituting
+another model or account after a failure.
+
 `start` records the received task ID through `checkpoint` before returning it. Runtime owns polling,
 capacity and durable operation state. `poll` returns `ready` for completed remote work; `collect`
 stores the image through `context.resources` and returns the Model's declared value. The Provider

package/examples/provider-package/packages/provider-images/src/provider.ts

@@ -1,6 +1,6 @@
 import { canonicalize, defineEndpointPackage, wakeAfter } from "@hypit/hypit/endpoint-kit";
 import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "@hypit/hypit/endpoint-kit";
-import { compileWireRequest, generationTypes, sealGeneratedImageSet } from "@hypit/hypit/generation";
+import { compileWireRequest, generationTypes, sealGeneratedImageSet, selectWireModelForRequest } from "@hypit/hypit/generation";
 import type { GenerationRequest, GenerationWireMapping } from "@hypit/hypit/generation";
 
 export const providerModule = { name: "@example/provider-images", version: "1" } as const;
@@ -25,6 +25,13 @@ function text(value: unknown): string {
   if (typeof value !== "string" || value.length === 0) throw new Error("Expected nonempty service text");
   return value;
 }
+// This illustrative service documents these fields as its public failure evidence.
+function publicFailure(value: unknown): { code: string; message: string } | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const error = value as Record<string, unknown>;
+  if (typeof error.code !== "string" || typeof error.message !== "string") return undefined;
+  return { code: error.code, message: error.message.replace(/https?:\/\/\S+/giu, "[redacted-url]") };
+}
 function address(value: string): string {
   const url = new URL(value);
   if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname))) {
@@ -57,7 +64,16 @@ export function createImageProvider(options: {
       ...init, headers: { ...init.headers, authorization: `Bearer ${secret}` },
       signal: AbortSignal.timeout(30_000),
     });
-    if (!response.ok) throw new Error(`Image service ${path} returned HTTP ${response.status}`);
+    if (!response.ok) {
+      let error: ReturnType<typeof publicFailure>;
+      try { error = publicFailure(object(await response.json()).error); }
+      catch { /* A missing public error body leaves the HTTP evidence intact. */ }
+      const requestId = response.headers.get("x-request-id");
+      throw Object.assign(new Error(`Image service ${init.method ?? "GET"} ${path} returned HTTP ${response.status}`
+        + (requestId === null ? "" : `; request=${requestId}`)
+        + (error === undefined ? "" : `; ${error.code}: ${error.message}`)),
+      error === undefined ? {} : { code: error.code });
+    }
     return object(await response.json());
   }
   const endpoint: AsyncEndpoint = {
@@ -65,7 +81,11 @@ export function createImageProvider(options: {
       const supported = support(context.need);
       if (supported.status === "unsupported") throw new Error(supported.reason);
       const secret = key(context.credentials);
-      const request = await compileWireRequest(mapping, context.need.constraints as unknown as GenerationRequest,
+      const authored = context.need.constraints as unknown as GenerationRequest;
+      const model = selectWireModelForRequest(mapping, authored);
+      // This service has no catalogue query; its known request limits were checked above.
+      await context.reportProgress?.({ phase: `Preparing image request: ${model}` });
+      const request = await compileWireRequest(mapping, authored,
         async (artifact) => {
           const bytes = await context.resources.get(artifact.resource);
           if (bytes === undefined) throw new Error("Reference image is unavailable");
@@ -74,6 +94,7 @@ export function createImageProvider(options: {
           });
           return address(text(upload.url));
         });
+      await context.reportProgress?.({ phase: `Submitting image request: ${model}` });
       const task = await json("/tasks", secret, {
         method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(request),
       });
@@ -87,15 +108,20 @@ export function createImageProvider(options: {
       if (task.state === "queued" || task.state === "running") {
         return wakeAfter({ id }, interval, Date.now(), { phase: task.state });
       }
-      if (task.state === "failed") return {
-        status: "failed", failure: { code: "IMAGE_SERVICE_FAILED", message: "Image service task failed" },
-      };
+      if (task.state === "failed") {
+        const error = publicFailure(task.error);
+        return { status: "failed", receipt: { id }, failure: {
+          code: error?.code ?? "IMAGE_SERVICE_FAILED",
+          message: `Image service task ${id} failed${error === undefined ? "" : `: ${error.message}`}`,
+        } };
+      }
       if (task.state !== "succeeded") throw new Error("Image service returned an unknown task state");
       return { status: "ready", handle: { id, url: address(text(task.url)) } };
     },
     async collect(context) {
       // The service returns a signed asset URL; account credentials go only to its API.
       const url = address(text(object(context.handle).url));
+      await context.reportProgress?.({ phase: "Receiving generated image" });
       const response = await fetcher(url, { signal: AbortSignal.timeout(60_000) });
       if (!response.ok) throw new Error(`Image download returned HTTP ${response.status}`);
       const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim();
@@ -113,8 +139,11 @@ export function createImageProvider(options: {
     actionLimits: { submit: { concurrency: 1 }, poll: { concurrency: 4 }, collect: { concurrency: 1 } },
     pricing: { kind: "page", url: `${base}/pricing` },
     async readPricing(context) {
-      const source = `${base}/rates?model=gpt-image-2`;
-      const rates = await json("/rates?model=gpt-image-2", key(await context.credentials()));
+      const model = selectWireModelForRequest(mapping, context.request.constraints as unknown as GenerationRequest,
+        context.request.pendingInputs?.map((input) => input.input));
+      const path = `/rates?model=${encodeURIComponent(model)}`;
+      const source = `${base}${path}`;
+      const rates = await json(path, key(await context.credentials()));
       return [{ source, data: canonicalize(rates), summary: text(rates.description) }];
     },
     capabilities: [{ capability, returns: generationTypes.imageSet, lifecycle: "asynchronous", supports: support, endpoint }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",

package/packages/cli/README.md

@@ -14,6 +14,28 @@ invent targets, candidates or Provider choices.
 Human and JSON output answer the same command-specific question. `--json` changes encoding;
 `--verbose` expands scope. Compiler, Runtime and Repository objects are not default reports.
 
+Design reports for the decision they support: retain relevant facts, uncertainty and usable object
+selectors, with direct access to omitted detail. Shorter output is useful when the next action
+remains well-founded. Observe the command result separately from service availability; titles,
+exit codes and JSON must preserve that distinction. A lifecycle refusal cannot become success just
+because a health probe is down. These rules concern presentation and composition of existing
+operations, not a prescribed production workflow.
+
+Argument errors use `CLI_USAGE` and point to the relevant `hypit help <command>`; JSON retains that
+command in `error.help`. Unknown help topics fail explicitly. Runtime and execution failures retain
+their own diagnostics and optional `--debug` trace. Result pagination changes only the `--before`
+cursor on the current query, preserving its project, Source filter and other options.
+
+Concrete follow-up commands keep the selected project and, for execution operations, Runtime Profile.
+Result-only commands need no Runtime. Arguments in displayed commands are quoted for POSIX shells
+or PowerShell on Windows, including paths with spaces. The CLI formats these existing commands;
+it does not choose which one the Agent must execute next.
+
+`build --follow` and `status --watch` report coalesced progress through `CliIo.writeProgress` when
+provided, including in JSON mode. The executable writes that channel to stderr; stdout remains the
+final machine result. A stopped Worker ends observation with evidence-reading commands, without
+promising to restart failed execution or describing the interruption as a Result storage failure.
+
 | Command | Default scope | Explicit detail |
 | --- | --- | --- |
 | `check` | Validation, targets and counts | `--verbose`: exported names/types and historical references |
@@ -56,6 +78,12 @@ not select it. The pointer is a file, separate from the Profile's `dataRoot`; a
 path is reported explicitly and preserved. Project selection is also available on `paths`, `doctor`, execution status/control,
 Runtime operations, `programs` and `auth`. Machine-wide `packages` operations have no project selector.
 
+`auth status <endpoint>` reports credential presence, write access, and the Provider's declared
+OAuth authorization endpoint when present. This describes how a subsequent `auth login` acquires a
+credential; it does not classify the secret already stored or verify remote account access.
+Without browser acquisition, login uses secure input. `--from <file>` explicitly imports a secret
+instead. Credential entry operates on an already declared Endpoint and changes no Provider or binding.
+
 `paths` shows the effective locations and whether the Profile came from a command argument, a project
 selection or neither. Its JSON fields `profileSource` and `selectionFile` expose that distinction; the
 selection-file location is shown even when no selection exists. `doctor` states whether it checked
@@ -113,6 +141,9 @@ flow.
 execution phases and Provider diagnostics. It reads a finished Result directly, without opening the
 Runtime; an active Build is read through Runtime control. The selected Repository handles file access.
 `--lines` limits the tail and the report states the omitted count; JSON carries records plus that count.
+An unavailable log reports `source: "unavailable"` and exits unsuccessfully; a readable log with zero
+records is a successful empty result. The human report distinguishes a finished Result with no log
+from a lookup that still needs the Build's Runtime or correct project selection.
 `inspect` exposes an available log separately from authored Outputs. `hypit runtime logs` reads the
 Worker process log instead, for Runtime startup or process-level failures.
 
@@ -123,6 +154,10 @@ CLI, Studio and creation tools call that same package; the CLI is not another en
 The same Endpoint scope reaches package preparation and Program operations. Omission means the whole
 Profile. Build preflight instead uses the Endpoints resolved for that Build's concrete requests.
 An unrelated offered capability does not add another credential or Program requirement.
+Program rows show the configured Endpoint selector alongside an internal Program ID when they differ.
+The `programs` JSON `ok` field reports whether this command succeeded; `ready` reports service
+readiness. Successful stopping can therefore report `ok: true` with `ready: false`. A declined stop remains visible even
+while the service is still preparing and cannot yet answer its health probe.
 
 Upstream package installation reports an `install.log` path at preparation time. Exact package
 releases coexist below the machine home, each with npm's own package.json and lockfile. `paths` shows

package/packages/cli/src/arguments.ts

@@ -13,6 +13,7 @@ import type {
   RuntimeSelectionCommand,
 } from "./command.js";
 import type { CliColorMode, CliOutputOptions } from "./output.js";
+import { CliUsageError } from "./usage-error.js";
 
 type RawOptions = {
   readonly presentation: CliOutputOptions;
@@ -48,6 +49,15 @@ type RawOptions = {
 const commonOptions = ["--json", "--color", "--no-color", "--verbose", "--debug"] as const;
 
 export function parseCommand(argv: readonly string[]): CliCommand {
+  try { return parseArguments(argv); }
+  catch (error) {
+    if (error instanceof CliUsageError) throw error;
+    throw new CliUsageError(error instanceof Error ? error.message : String(error),
+      argv[0] === undefined ? "hypit help" : `hypit help ${argv[0]}`, { cause: error });
+  }
+}
+
+function parseArguments(argv: readonly string[]): CliCommand {
   const [command, ...tail] = argv;
   switch (command) {
     case "check": {
@@ -246,7 +256,8 @@ export function parseCommand(argv: readonly string[]): CliCommand {
         ...optionalPackageRoot(options),
       };
     }
-    default: throw new Error(usage());
+    default: throw new CliUsageError(command === undefined ? "A command is required"
+      : `Unknown command ${JSON.stringify(command)}`, "hypit help");
   }
 }
 

package/packages/cli/src/command-hint.ts

@@ -0,0 +1,20 @@
+/** Scope belongs to the invocation; a suggested command must keep the same target. */
+export type CommandScope = {
+  readonly projectRoot?: string;
+  readonly runtimeProfile?: string;
+};
+
+/** Display copyable arguments for POSIX shells or PowerShell, without expanding their contents. */
+export function commandHint(
+  args: readonly string[],
+  scope: CommandScope = {},
+  shell: "posix" | "powershell" = process.platform === "win32" ? "powershell" : "posix",
+): string {
+  const quote = (value: string): string => /^[a-zA-Z0-9_./:@=+-]+$/u.test(value)
+    ? value
+    : `'${value.replaceAll("'", shell === "powershell" ? "''" : "'\"'\"'")}'`;
+  return ["hypit", ...args,
+    ...(scope.projectRoot === undefined ? [] : ["--workspace", scope.projectRoot]),
+    ...(scope.runtimeProfile === undefined ? [] : ["--runtime", scope.runtimeProfile]),
+  ].map(quote).join(" ");
+}

package/packages/cli/src/commands/environment.ts

@@ -5,12 +5,13 @@ import type { NodeRuntimeHost } from "@hypit/runtime-host-node";
 import { hypitHostPackageRoot, inspectHostPackage, prepareHostPackages } from "@hypit/runtime-host-node";
 
 import type { CliCommand, EnvironmentCommand } from "../command.js";
+import { commandHint } from "../command-hint.js";
 import type { CliDistribution } from "../distribution.js";
 import { acquireOAuthCredential } from "../oauth.js";
 import { writeCliOutput } from "../output.js";
 import type { CliIo } from "../output.js";
 import { hypitHostStateRoot, hypitProjectStateRoot } from "../paths.js";
-import type { CliManagedProgramReport, CliRuntimeController } from "../runtime-port.js";
+import type { CliManagedProgramProgress, CliManagedProgramReport, CliRuntimeController } from "../runtime-port.js";
 import type { OperationalWriter } from "./types.js";
 
 function programRecord(item: CliManagedProgramReport) {
@@ -27,8 +28,12 @@ function programDescription(item: CliManagedProgramReport): string {
     ...(item.detail === undefined ? [] : [item.detail]),
   ])];
   return `${item.id}: ${item.state.state}${details.length === 0 ? "" : ` — ${details.join("; ")}`}`
+    + (item.endpoint === item.id ? "" : ` · endpoint ${item.endpoint}`)
     + (item.pid === undefined ? "" : ` · PID ${item.pid}`)
-    + (item.logPath === undefined ? "" : ` · log ${item.logPath}`);
+    + (item.logPath === undefined ? "" : ` · log ${item.logPath}`)
+    + (item.installationLogPath === undefined || item.installationLogPath === item.logPath
+      ? "" : ` · installation log ${item.installationLogPath}`)
+    + (item.errorLogPath === undefined ? "" : ` · stderr ${item.errorLogPath}`);
 }
 
 export function isEnvironmentCommand(args: CliCommand): args is EnvironmentCommand {
@@ -58,10 +63,11 @@ export async function runEnvironmentCommand(input: {
   const selectionDescription = profileSource === "argument"
     ? "command argument (this invocation only)"
     : runtimeSelectionFile ?? "none";
-  const reportProgramProgress = args.presentation.json
+  const progressWriter = args.presentation.json ? io.writeProgress : io.writeProgress ?? io.write;
+  const reportProgramProgress = progressWriter === undefined
     ? undefined
-    : (event: { readonly id: string; readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready"; readonly logPath?: string }): void => {
-      if (!args.presentation.verbose && event.phase !== "installing" && event.phase !== "starting") return;
+    : (event: CliManagedProgramProgress): void => {
+      if (!args.presentation.verbose && event.detail === undefined && event.phase !== "installing" && event.phase !== "starting") return;
       const verb = {
         checking: "Checking",
         installing: "Installing",
@@ -69,12 +75,12 @@ export async function runEnvironmentCommand(input: {
         waiting: "Waiting for",
         ready: "Ready",
       }[event.phase];
-      io.write(`  · ${verb} ${event.id}${event.logPath === undefined ? "" : ` · log ${event.logPath}`}\n`);
+      progressWriter(`  · ${verb} ${event.id}${event.detail === undefined ? "" : ` — ${event.detail}`}${event.logPath === undefined ? "" : ` · log ${event.logPath}`}\n`);
     };
-  const reportPackageProgress = args.presentation.json
+  const reportPackageProgress = progressWriter === undefined
     ? undefined
     : (event: { readonly specifier: string; readonly phase: "checking" | "installing" | "ready"; readonly logPath?: string }): void => {
-      if (event.phase === "installing") io.write(`  · Installing ${event.specifier}${event.logPath === undefined ? "" : ` · log ${event.logPath}`}\n`);
+      if (event.phase === "installing") progressWriter(`  · Installing ${event.specifier}${event.logPath === undefined ? "" : ` · log ${event.logPath}`}\n`);
     };
   const reportCredentialProgress = args.presentation.json
     ? io.writeProgress
@@ -183,22 +189,25 @@ export async function runEnvironmentCommand(input: {
         ? await controller.programs.down(args.endpoints === undefined ? {} : { endpoints: args.endpoints })
         : await controller.programs.report(args.endpoints === undefined ? {} : { endpoints: args.endpoints });
     const ready = result.programs.every((item) => item.state.state === "ready");
-    const desiredState = args.action === "down" ? !result.programs.some((item) => item.state.state === "ready") : ready;
-    const lifecycleOk = args.action === "status" || desiredState;
     const needsAttention = (item: typeof result.programs[number]) => args.action === "down"
-      ? item.state.state === "ready" : item.state.state !== "ready";
+      ? item.state.state !== "down" || (item.action !== "stopped" && item.action !== "nothing-to-stop")
+      : item.state.state !== "ready";
+    // Readiness describes the service, not whether a stop was performed. An owned process can
+    // still be loading, and another command may have declined a concurrent stop during preparation.
+    const lifecycleOk = args.action === "status" || !result.programs.some(needsAttention);
     const relevant = result.programs.filter((item) => args.presentation.verbose || args.action === "status" || needsAttention(item));
     const urgent = relevant.filter(needsAttention);
     const shownPrograms = [...urgent, ...relevant.filter((item) => !needsAttention(item)).slice(0, Math.max(0, args.limit - urgent.length))];
     const omittedPrograms = relevant.length - shownPrograms.length;
     const title = args.action === "up"
-      ? desiredState ? "External programs ready" : "External programs need attention"
+      ? lifecycleOk ? "External programs ready" : "External programs need attention"
       : args.action === "down"
-        ? desiredState ? "External programs stopped" : "Some external programs are still running"
+        ? lifecycleOk ? "External programs stopped" : "External program stop needs attention"
         : "External program status";
     write({
       format: "hypit.cli-programs@1",
       action: args.action,
+      ok: lifecycleOk,
       ready,
       programCount: result.programs.length,
       readyCount: result.programs.filter((item) => item.state.state === "ready").length,
@@ -278,9 +287,12 @@ export async function runEnvironmentCommand(input: {
       const worker = await controller.worker.down({
         ...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
       });
+      const stopped = worker.state === "stopped";
       write({ format: "hypit.cli-runtime-down@1", worker: worker.state },
-        "Runtime Worker is down", "success", [["Worker", worker.state]],
-        ["Managed programs were left running. Stop them explicitly with hypit programs down."]);
+        stopped ? "Runtime Worker is down" : "Runtime Worker is still running",
+        stopped ? "success" : "warning", [["Worker", worker.state]],
+        [`Managed programs were left running. To stop them: ${commandHint(["programs", "down"], { projectRoot, runtimeProfile: resolve(profile) })}`]);
+      if (!stopped) io.setExitCode?.(1);
       return;
     }
 
@@ -324,7 +336,8 @@ export async function runEnvironmentCommand(input: {
       };
       write(machine, attention
         ? "Local Runtime needs attention"
-        : ready ? "Local Runtime ready" : "Runtime Worker stopped",
+        : ready ? "Local Runtime ready" : worker.state === "running"
+          ? "Runtime Worker running; Programs not ready" : "Runtime Worker stopped",
       attention ? "warning" : ready ? "success" : "info", [
         ["Worker", worker.state],
         ["Active Builds", String(activity.builds.length)],
@@ -365,6 +378,10 @@ export async function runEnvironmentCommand(input: {
           kind: item.kind,
           configured: item.configured,
           writable: item.writable,
+          ...(item.acquisition === undefined ? {} : { acquisition: {
+            kind: item.acquisition.kind,
+            authorizationEndpoint: item.acquisition.authorizationEndpoint,
+          } }),
         }));
         write({
           format: "hypit.cli-auth-status@1",
@@ -374,8 +391,12 @@ export async function runEnvironmentCommand(input: {
         }, "Credential status", "info", [
           ["Endpoint", args.endpoint],
           ["Configured", `${credentials.filter((item) => item.configured).length}/${credentials.length}`],
-        ], credentials.slice(0, args.limit).map((item) =>
-          `${item.slot}: ${item.configured ? "configured" : "missing"} · ${item.writable ? "writable" : "read-only"}`));
+        ], credentials.slice(0, args.limit).map((item) => {
+          const entry = !item.writable ? "managed by its external credential source"
+            : item.acquisition === undefined ? "login uses secure secret input"
+            : `login opens OAuth: ${item.acquisition.authorizationEndpoint}`;
+          return `${item.slot}: ${item.configured ? "configured" : "missing"} · ${item.writable ? "writable" : "read-only"} · ${entry}`;
+        }));
       } else if (args.action === "login") {
         const [item] = credentials;
         if (item === undefined) throw new Error(`Endpoint ${args.endpoint} has no matching credential`);

package/packages/cli/src/commands/execution.ts

@@ -1,8 +1,11 @@
+import { resolve } from "node:path";
+
 import { readExecutionLog } from "@hypit/runtime";
 import type { BuildResultManifest, BuildResultRepository } from "@hypit/build-result";
 import type { NodeRuntimeHost } from "@hypit/runtime-host-node";
 
 import type { CliCommand, ExecutionCommand } from "../command.js";
+import { commandHint } from "../command-hint.js";
 import { activityObservationKey, buildProgressLines, buildProgressView, observeBuildView } from "../observation.js";
 import type { CliIo } from "../output.js";
 import type { CliRuntimeController } from "../runtime-port.js";
@@ -37,6 +40,7 @@ export function isExecutionCommand(args: CliCommand): args is ExecutionCommand {
 /** Inspect or control accepted Build work. Observation never owns execution. */
 export async function runExecutionCommand(input: {
   readonly args: ExecutionCommand;
+  readonly projectRoot: string;
   readonly runtimeProfile: string | undefined;
   readonly resolveProjectRuntime?: () => Promise<string | undefined>;
   readonly io: CliIo;
@@ -46,6 +50,10 @@ export async function runExecutionCommand(input: {
   readonly write: OperationalWriter;
 }): Promise<void> {
   const { args, runtimeProfile, io, runtimeHost, runtimeController, openProjectResults, write } = input;
+  const commandScope = {
+    projectRoot: input.projectRoot,
+    ...(runtimeProfile === undefined ? {} : { runtimeProfile: resolve(runtimeProfile) }),
+  };
   if (args.command === "logs") {
     const opened = await openProjectResults();
     let source: "runtime" | "result" | "unavailable" = "unavailable";
@@ -83,13 +91,19 @@ export async function runExecutionCommand(input: {
     const records = view?.records ?? [];
     const omitted = (view?.total ?? 0) - records.length;
     write({ format: "hypit.cli-logs@1", build: args.build, source, records, omittedRecords: omitted },
-      view === undefined ? "No execution log recorded" : "Build execution log", "info",
+      view === undefined ? "Execution log unavailable" : "Build execution log", view === undefined ? "warning" : "info",
       [["Build", args.build], ["Source", source]], [
+        ...(view !== undefined ? [] : [finished
+          ? "This Result has no saved execution log."
+          : activeProfile === undefined
+            ? "No saved log found in this project. Select the Build's Runtime with --runtime <profile> to check active execution."
+            : "No log found in this project's Results or the selected Runtime. Check the Build id and project selection."]),
         ...(omitted > 0 ? [`Showing last ${records.length} records; ${omitted} earlier records omitted. Use --lines to read more.`] : []),
         ...records.map((record) => `${new Date(record.time).toISOString()}  ${record.endpoint}  ${record.command}  ${
           record.kind === "phase" ? record.phase : record.kind === "diagnostic" || record.kind === "failed"
             ? `${record.kind}: ${record.message}` : record.kind}`),
       ]);
+    if (view === undefined) io.setExitCode?.(1);
     return;
   }
 
@@ -158,7 +172,7 @@ export async function runExecutionCommand(input: {
           controller.worker.status(),
         ]);
         const builds = activity.builds.slice(0, args.limit).map((item) => {
-          const status = buildStatusView({ id: item.id, runtime: item });
+          const status = buildStatusView({ id: item.id, runtime: item, commandScope });
           return {
             id: item.id,
             work: status.work,
@@ -213,23 +227,23 @@ export async function runExecutionCommand(input: {
       let result: BuildResultManifest | undefined;
       let resultReadError: string | undefined;
       let openedResults: Awaited<ReturnType<OpenProjectResults>> | undefined;
+      if (args.watch && view !== undefined && view.issue === undefined) {
+        const controller = await runtimeController(runtimeProfile);
+        view = await observeBuildView(runtime, args.build, view, {
+          ...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
+          controller,
+          commandScope,
+          onProgress: (progress) => {
+            const report = io.writeProgress ?? (args.presentation.json ? undefined : io.write);
+            for (const line of buildProgressLines(progress, {
+              verbose: args.presentation.verbose,
+              limit: args.limit,
+            })) report?.(`${line}\n`);
+          },
+        });
+      }
       try {
         openedResults = await openProjectResults();
-        if (args.watch && view !== undefined && view.issue === undefined) {
-          const controller = await runtimeController(runtimeProfile);
-          view = await observeBuildView(runtime, args.build, view, {
-            ...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
-            controller,
-            ...(args.presentation.json ? {} : {
-              onProgress: (progress) => {
-                for (const line of buildProgressLines(progress, {
-                  verbose: args.presentation.verbose,
-                  limit: args.limit,
-                })) io.write(`${line}\n`);
-              },
-            }),
-          });
-        }
         result = await openedResults.repository.read(args.build);
       } catch (error) {
         resultReadError = error instanceof Error ? error.message : String(error);
@@ -244,6 +258,7 @@ export async function runExecutionCommand(input: {
       const issue = view?.issue;
       const build = !found ? null : buildStatusView({
         id: view?.id ?? result!.id,
+        commandScope,
         ...(view === undefined ? {} : { runtime: view }),
         ...(result === undefined ? {} : { result }),
         ...(resultReadError === undefined ? {} : { resultReadError }),
@@ -332,7 +347,7 @@ export async function runExecutionCommand(input: {
         outcome: finished.outcome,
         ...(finished.issue === undefined ? {} : { attention: {
           message: finished.issue.message,
-          action: `hypit result finish ${args.build}`,
+          action: commandHint(["result", "finish", args.build], commandScope),
         } }),
       }, finished.issue === undefined ? "Result finished" : "Result still needs attention",
       finished.issue === undefined ? "success" : "error", [
@@ -350,6 +365,7 @@ export async function runExecutionCommand(input: {
       : await openedResults.repository.read(args.build).finally(async () => await openedResults.close());
     const build = active === undefined && finished === undefined ? null : buildStatusView({
       id: args.build,
+      commandScope,
       ...(active === undefined ? {} : { runtime: active }),
       ...(finished === undefined ? {} : { result: finished }),
     });

package/packages/cli/src/commands/results.ts

@@ -13,6 +13,7 @@ import {
   projectPath,
 } from "../view.js";
 import type { OperationalWriter } from "./types.js";
+import { commandHint } from "../command-hint.js";
 
 export function isProjectResultCommand(args: CliCommand): args is ProjectResultCommand {
   return args.command === "builds" || args.command === "history" || args.command === "inspect"
@@ -54,7 +55,9 @@ export async function runProjectResultCommand(input: {
       const label = item.title === undefined ? item.id : `${item.title} · ${item.id}`;
       const run = item.run === undefined ? "" : ` · ${item.run}`;
       return `${label}: ${item.outcome} · ${new Date(item.createdAt).toLocaleString()}${run} · ${item.targetCount} target${item.targetCount === 1 ? "" : "s"}`;
-    }).concat(page.next === undefined ? [] : [`Older    hypit builds --before ${page.next}`]));
+    }).concat(page.next === undefined ? [] : [
+      `Older    Repeat this command with --before ${page.next}, keeping the other options.`,
+    ]));
     return;
   }
 
@@ -89,7 +92,9 @@ export async function runProjectResultCommand(input: {
       const label = item.title === undefined ? item.build : `${item.title} · ${item.build}`;
       return `${label}: ${item.outcome} · ${new Date(item.createdAt).toLocaleString()}`
         + (args.presentation.verbose ? ` · ${item.output.kind} · ${item.output.type}` : "");
-    }).concat(page.next === undefined ? [] : [`Older    hypit history ${args.outputName} --before ${page.next}`]));
+    }).concat(page.next === undefined ? [] : [
+      `Older    Repeat this command with --before ${page.next}, keeping the other options.`,
+    ]));
     return;
   }
 
@@ -116,7 +121,7 @@ export async function runProjectResultCommand(input: {
         ] : []),
       ], [
         ...(build.failure === undefined ? [] : [`Reason    ${build.failure}`]),
-        ...(build.executionLog === undefined ? [] : [`Execution log    hypit logs ${build.id}`]),
+        ...(build.executionLog === undefined ? [] : [`Execution log    ${commandHint(["logs", build.id], { projectRoot })}`]),
         ...(build.operations ?? []).map((operation) =>
           `${operation.endpoint}: ${operation.status}${operation.receipt === undefined ? "" : ` · task ${operation.receipt.id}`}`
           + (operation.failure === undefined ? "" : ` · ${operation.failure.code}: ${operation.failure.message}`)),