@hraness/slopcamera 3.7.0 → 3.8.1

package/apps/desktop/cli/help.ts

@@ -39,6 +39,11 @@ Commands:
                                  Buy and inspect hosted generation credits
   media audio|color              Apply local non-destructive audio and video effects
   outputs                        Print the agent outputs directory
+  outputs list|open|reveal       List the newest outputs or open one on this Mac
+  status                         What Slopcamera is doing, credits and newest outputs
+  tui [--snapshot]               The status screen; --snapshot prints it once
+  commands [--json]              List every command with what it may change
+  legacy retire                  Stop the old menu bar opening at login
   recordings list               List recording bundles
   projects list|create           List projects or create one from a recording
   project inspect|add|edit|render
@@ -65,28 +70,6 @@ ${slopcameraSupportHelpLine()}`;
 
 const HELP: Readonly<Record<string, string>> = {
   advanced: `${slopcameraSupportAdvancedHelp()}`,
-  menubar: `Usage:
-  slopcamera menubar [--foreground|--background] [--json]
-  slopcamera menubar install|uninstall|status|start [--json]
-
-Shows what Slopcamera is doing in the menu bar: a render in progress, how the
-last job ended and your last known credits balance, plus your newest outputs.
-It only reads that status and the outputs folder (slopcamera outputs).
-
-  menubar               Open it now; it closes when this command ends
-  menubar start         Open it now and return (same as --background)
-  menubar install       Open it every time you log in
-  menubar uninstall     Stop opening it at login and remove the installed copy
-  menubar status        Check whether it opens at login and is running
-
-If it's already in your menu bar, starting it again says so and succeeds.
-macOS shows a notice that slopcamera-menubar can open at login. Turn it off any
-time in System Settings › General › Login Items & Extensions.
-
-The menu bar isn't in released packages yet, so it isn't listed in
-slopcamera help. In a Slopcamera checkout, build it with
-cargo build --release --manifest-path desktop/Cargo.toml and slopcamera finds
-it; elsewhere, set SLOPCAMERA_MENUBAR to the built file.`,
   capabilities: `Usage: slopcamera capabilities [--json]
 
 Print the exact statically assembled capability manifest for this CLI build. Each module owns named operation, workflow, MCP-tool, command, and runtime-profile identities. The manifest includes trust classes, resource/effect policies, runtime requirements, qualification status, and a canonical SHA-256. It reads no workspace source, loads no plugin, probes no runtime, and grants no authority. Use doctor separately to inspect this machine's currently available executables.`,
@@ -729,7 +712,7 @@ export function commandHelp(topic: readonly string[]): string {
 
 export function completions(words: readonly string[]): readonly string[] {
   const topLevel = [
-    "capabilities", "operations", "diagram", "direct", "studio", "image", "html", "style", "workflows", "code", "runs", "doctor", "ai", "credits", "media", "menubar", "support", "outputs", "recordings", "projects", "project", "scene", "inspect", "events", "edit", "analyze", "align", "faces", "fillers", "render", "assets",
+    "capabilities", "operations", "diagram", "direct", "studio", "image", "html", "style", "workflows", "code", "runs", "doctor", "ai", "credits", "media", "support", "outputs", "status", "tui", "commands", "legacy", "recordings", "projects", "project", "scene", "inspect", "events", "edit", "analyze", "align", "faces", "fillers", "render", "assets",
   ];
   if (words.length <= 1) return topLevel;
   const command = words[0];
@@ -755,7 +738,8 @@ export function completions(words: readonly string[]): readonly string[] {
     if (words[1] === "direction") return ["check", "plan", "gallery"];
     if (words[1] === "effects") return ["check", "plan", "bake"];
     if (words[1] === "behavior") return ["check", "bake", "gallery", "audit"];
-    return ["init", "check", "inspect", "diff", "patch", "evaluate", "audit", "render-audit", "solve", "review", "camera-track", "generate", "plan", "render", "direction", "effects", "behavior", "temporal-audit"];
+    if (words[1] === "design") return ["catalog", "init", "inspect", "set", "compile", "gallery"];
+    return ["init", "check", "inspect", "diff", "patch", "evaluate", "audit", "render-audit", "solve", "review", "camera-track", "generate", "plan", "render", "direction", "effects", "behavior", "design", "temporal-audit"];
   }
   if (command === "edit") return ["init", "show", "trim", "cut", "speed", "zoom", "overlay", "cursor", "clicks", "keystrokes", "typed-text"];
   if (command === "analyze") return ["faces", "inactivity", "zooms", "music", "scenes", "speech"];
@@ -767,5 +751,7 @@ export function completions(words: readonly string[]): readonly string[] {
   if (command === "media") return ["audio", "color"];
   if (command === "render") return ["plan", "run"];
   if (command === "assets") return ["emoji"];
+  if (command === "outputs") return ["list", "open", "reveal"];
+  if (command === "legacy") return ["retire"];
   return [];
 }

package/apps/desktop/cli/legacy-login.ts

@@ -0,0 +1,184 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readdirSync, readSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+import {
+  MAX_LOGIN_ITEM_BYTES,
+  retireLegacyLoginItem,
+  type LegacyLoginItem,
+  type Retired,
+} from "@hraness/desktop-foundation/retire";
+
+import { CliError } from "./errors";
+
+/**
+ * Login items earlier Slopcamera releases wrote to start the retired menu
+ * bar. Newest first: the desktop-foundation helper's item, the name that
+ * helper used before, and the plist the CLI itself wrote before that.
+ */
+export const LEGACY_LOGIN_LABELS = [
+  "app.hraness.slopcamera",
+  "app.hraness.companion.slopcamera",
+  "com.hraness.slopcamera.menubar",
+] as const;
+
+const OLD_CLI_LABEL = "com.hraness.slopcamera.menubar";
+const MENU_BINARY = /\/slopcamera-menubar$/u;
+const LOCAL_APP = /\/Slopcamera\.app\/Contents\/MacOS\/[^/]+$/u;
+
+function xml(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+
+function unxml(value: string): string {
+  return value.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", '"').replaceAll("&apos;", "'").replaceAll("&amp;", "&");
+}
+
+/** The exact plist the old `slopcamera menubar install` wrote. */
+export function oldCliPlist(binary: string): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>${xml(OLD_CLI_LABEL)}</string><key>ProgramArguments</key><array><string>${xml(binary)}</string></array><key>RunAtLoad</key><true/><key>KeepAlive</key><false/><key>ProcessType</key><string>Interactive</string><key>LimitLoadToSessionType</key><string>Aqua</string></dict></plist>\n`;
+}
+
+function programArguments(text: string): string[] {
+  const array = /<key>ProgramArguments<\/key><array>((?:<string>[^<]*<\/string>)*)<\/array>/u.exec(text);
+  if (array === null) return [];
+  return [...array[1]!.matchAll(/<string>([^<]*)<\/string>/gu)].map(match => unxml(match[1]!));
+}
+
+/**
+ * True only for an item Slopcamera wrote for its menu bar. The helper's
+ * items carry a header with the SHA-256 of the body, so an edited file is
+ * not ours. The old CLI item must match what that CLI wrote byte for byte.
+ */
+export function isSlopcameraMenubarItem(item: LegacyLoginItem): boolean {
+  if (item.label === OLD_CLI_LABEL) {
+    const [program, ...rest] = programArguments(item.text);
+    return program !== undefined && rest.length === 0 && MENU_BINARY.test(program) && item.text === oldCliPlist(program);
+  }
+  const newline = item.text.indexOf("\n");
+  if (newline < 0) return false;
+  const body = item.text.slice(newline + 1);
+  const digest = createHash("sha256").update(body).digest("hex");
+  if (item.text.slice(0, newline + 1) !== `<!-- hraness-companion autostart slopcamera sha256:${digest} -->\n`) return false;
+  if (!body.includes(`<key>Label</key><string>${xml(item.label)}</string>`)) return false;
+  const [program] = programArguments(body);
+  return program !== undefined && (MENU_BINARY.test(program) || LOCAL_APP.test(program));
+}
+
+export type LegacyLoginState = "none" | "found" | "not-ours";
+
+export interface LegacyLoginReport {
+  readonly state: LegacyLoginState;
+  /** The label of the item found, when there is one. */
+  readonly label?: string;
+}
+
+function readSmallFile(path: string): string | undefined {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = fstatSync(fd);
+    if (!info.isFile() || info.size > MAX_LOGIN_ITEM_BYTES || info.uid !== process.getuid?.()) return undefined;
+    const bytes = Buffer.alloc(info.size);
+    let count = 0;
+    while (count < bytes.length) {
+      const read = readSync(fd, bytes, count, bytes.length - count, count);
+      if (read === 0) break;
+      count += read;
+    }
+    return bytes.subarray(0, count).toString("utf8");
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function launchAgents(home: string | undefined): string | undefined {
+  return home === undefined || home === "" || !isAbsolute(home) ? undefined : join(home, "Library", "LaunchAgents");
+}
+
+/** Reads the LaunchAgents folder and reports the old menu bar item. Changes nothing. */
+export function inspectLegacyLogin(home: string | undefined): LegacyLoginReport {
+  const directory = launchAgents(home);
+  if (directory === undefined) return { state: "none" };
+  let foreign: string | undefined;
+  for (const label of LEGACY_LOGIN_LABELS) {
+    const path = join(directory, `${label}.plist`);
+    try {
+      lstatSync(path);
+    } catch {
+      continue;
+    }
+    const text = readSmallFile(path);
+    if (text !== undefined && isSlopcameraMenubarItem({ label, path, text })) return { state: "found", label };
+    foreign ??= label;
+  }
+  return foreign === undefined ? { state: "none" } : { state: "not-ours", label: foreign };
+}
+
+export interface RetireDependencies {
+  readonly bootout?: (label: string) => Promise<void>;
+  readonly now?: () => Date;
+}
+
+/**
+ * Stops the old menu bar starting at login: boots out its label and renames
+ * the plist to `<name>.retired-<ms>`. Nothing is deleted, no process is
+ * signalled by pid, and items Slopcamera did not write are left alone.
+ */
+export async function retireLegacyLogin(home: string | undefined, dependencies: RetireDependencies = {}): Promise<Retired[]> {
+  if (launchAgents(home) === undefined) throw new CliError("unavailable", "HOME must be an absolute directory to look for the old menu bar login item.");
+  const retired: Retired[] = [];
+  // One call retires the first match; repeat so every old copy is moved aside.
+  for (let attempt = 0; attempt < LEGACY_LOGIN_LABELS.length; attempt += 1) {
+    const labels = LEGACY_LOGIN_LABELS.filter(label => !retired.some(item => item.label === label));
+    const result = await retireLegacyLoginItem({
+      home: home!,
+      labels,
+      accepts: isSlopcameraMenubarItem,
+      ...(dependencies.bootout === undefined ? {} : { bootout: dependencies.bootout }),
+      ...(dependencies.now === undefined ? {} : { now: dependencies.now }),
+    });
+    if (result === null) break;
+    retired.push(result);
+  }
+  return retired;
+}
+
+export interface RetiredLegacyLogin {
+  readonly label: string;
+  readonly path: string;
+  /** Puts the item back and loads it, undoing `slopcamera legacy retire`. */
+  readonly restore: string;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/** Login items `legacy retire` moved aside, with the command that restores each. Changes nothing. */
+export function retiredLegacyLogins(home: string | undefined): RetiredLegacyLogin[] {
+  const directory = launchAgents(home);
+  if (directory === undefined) return [];
+  let names: string[];
+  try {
+    names = readdirSync(directory);
+  } catch {
+    return [];
+  }
+  const found: RetiredLegacyLogin[] = [];
+  for (const label of LEGACY_LOGIN_LABELS) {
+    const prefix = `${label}.plist.retired-`;
+    for (const name of names.filter(item => item.startsWith(prefix) && /^[0-9]{1,16}$/u.test(item.slice(prefix.length))).sort()) {
+      const path = join(directory, name);
+      const original = join(directory, `${label}.plist`);
+      found.push({
+        label,
+        path,
+        restore: `mv -n ${shellQuote(path)} ${shellQuote(original)} && launchctl bootstrap gui/$(id -u) ${shellQuote(original)}`,
+      });
+    }
+  }
+  return found;
+}

package/apps/desktop/cli/main.ts

@@ -5,6 +5,7 @@ import { runProductSupportCommand, showProductSupportInvitation, standaloneSuppo
 import { parseCliArgs } from "./args";
 import { runCli } from "./commands";
 import { asCliError, CliError, EXIT_CODE } from "./errors";
+import { isRegistryCommand, runRegistry } from "./registry";
 import { BunProcessRunner, processIo } from "./io";
 import { resolveRepositoryPaths } from "./paths";
 import {
@@ -42,6 +43,13 @@ export async function main(
     return await runProductSupportCommand(argv.slice(1),
       supportEnvironment === undefined ? {} : { env: supportEnvironment });
   }
+  if (isRegistryCommand(argv)) {
+    // status, tui, commands, legacy retire and outputs list|open|reveal
+    // answer in the shared desktop-foundation envelope.
+    return await runRegistry(argv, { stdout: process.stdout, stderr: process.stderr, env: process.env }, {
+      env: process.env, platform: process.platform, now: () => new Date(),
+    });
+  }
   const unifiedArgv = canonicalizeUnifiedCliArgs(argv);
   const portableExitCode = await runPortableSurface(unifiedArgv, portableDependencies);
   if (portableExitCode !== undefined) return portableExitCode;

package/apps/desktop/cli/outputs.ts

@@ -0,0 +1,19 @@
+import { dirname, join, sep } from "node:path";
+
+import type { CliIo } from "./io";
+import { writeJson, writeLine } from "./io";
+import { ensurePrivateDirectory } from "./paths";
+
+/** The directory agents write user-facing outputs into. */
+export function outputsDirectory(stateRoot: string): string {
+  const productRoot = stateRoot.endsWith(`${sep}cli`) ? dirname(stateRoot) : stateRoot;
+  return join(productRoot, "outputs");
+}
+
+/** `slopcamera outputs`: creates the private outputs folder and prints its path. */
+export async function reportOutputsRoot(io: CliIo, stateRoot: string, asJson: boolean): Promise<void> {
+  const directory = outputsDirectory(stateRoot);
+  await ensurePrivateDirectory(directory);
+  if (asJson) writeJson(io, { outputs: directory });
+  else writeLine(io, directory);
+}

package/apps/desktop/cli/registry.ts

@@ -0,0 +1,314 @@
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  defineRegistry,
+  HranessError,
+  okEnvelope,
+  runCli as runRegistryCli,
+  type CliIO,
+  type ErrorCode,
+  type Registry,
+  type Verb,
+} from "@hraness/desktop-foundation/registry";
+import { chooseMode, renderSnapshot, runTui, type TuiIO } from "@hraness/desktop-foundation/tui";
+
+import { SLOPCAMERA_VERSION } from "../../../src/version";
+import { listOutputs, OUTPUTS_LIMIT, statusEnvelope, statusViews, STATUS_SCHEMA, type StatusOutputs } from "./desktop-status";
+import type { ProcessRunner } from "./io";
+import { CliError } from "./errors";
+import { BunProcessRunner } from "./io";
+import { readActivityStatus } from "./activity-status";
+import { inspectLegacyLogin, retireLegacyLogin, type RetireDependencies } from "./legacy-login";
+import { outputsDirectory } from "./outputs";
+import { defaultCliStateRoot } from "./paths";
+import { CLI_VERBS, type VerbRow } from "./verbs";
+
+/**
+ * The verbs `slopcamera` answers through the desktop-foundation registry:
+ * `status`, `tui`, `commands`, `legacy retire` and `outputs list|open|reveal`.
+ * Every other verb keeps its own parser in `args.ts`; the registry still
+ * lists it with its class so `commands --json` covers the whole CLI.
+ */
+export const PRODUCT = "slopcamera";
+export const OUTPUTS_LIST_LIMIT = 200;
+
+/** First words (and `outputs` sub-verbs) the registry answers. */
+export function isRegistryCommand(argv: readonly string[]): boolean {
+  const [first, second] = argv;
+  if (first === "status" || first === "tui" || first === "commands" || first === "legacy") return true;
+  return first === "outputs" && (second === "list" || second === "open" || second === "reveal");
+}
+
+export interface RegistryDependencies {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly platform: NodeJS.Platform;
+  readonly now: () => Date;
+  readonly stateRoot?: string;
+  readonly version?: string;
+  readonly runner?: ProcessRunner;
+  readonly retire?: RetireDependencies;
+  readonly stdoutIsTerminal?: boolean;
+  readonly tuiIo?: TuiIO;
+}
+
+function stateRootOf(deps: RegistryDependencies): string {
+  return deps.stateRoot ?? defaultCliStateRoot(deps.platform, deps.env);
+}
+
+/** Loads everything `status` and `tui` show. Reads only; creates nothing. */
+export function loadStatus(deps: RegistryDependencies) {
+  const stateRoot = stateRootOf(deps);
+  return statusEnvelope({
+    version: deps.version ?? SLOPCAMERA_VERSION,
+    status: readActivityStatus(stateRoot),
+    outputs: listOutputs(outputsDirectory(stateRoot), OUTPUTS_LIMIT),
+    legacyLogin: inspectLegacyLogin(deps.env.HOME),
+    now: deps.now(),
+  });
+}
+
+function schemaFor(path: readonly string[]): string {
+  return `${PRODUCT}.${path.join(".")}/1`;
+}
+
+/**
+ * One output by its file name, as `outputs list` prints it. Only a plain
+ * name of a regular, visible file directly in the outputs folder is
+ * accepted, so the verb can never open anything else.
+ */
+export function outputPath(root: string, name: string | undefined): string {
+  if (name === undefined || name === "") throw new HranessError("usage", "Name one output, as `slopcamera outputs list` prints it.");
+  if (name.includes("/") || name.includes("\\") || name.startsWith(".") || name.includes("\0") || name.length > 255) {
+    throw new HranessError("usage", "Give the output's file name only, as `slopcamera outputs list` prints it.");
+  }
+  const path = join(root, name);
+  let regular = false;
+  try {
+    regular = lstatSync(path).isFile();
+  } catch {
+    regular = false;
+  }
+  if (!regular) {
+    throw new HranessError("not-found", `No output named ${JSON.stringify(name)}.`, undefined, [
+      { command: `${PRODUCT} outputs list --json`, why: "List the outputs by name.", audience: "agent" },
+    ]);
+  }
+  return path;
+}
+
+async function finder(deps: RegistryDependencies, argv: readonly [string, ...string[]]): Promise<void> {
+  if (deps.platform !== "darwin") {
+    throw new HranessError("unsupported-platform", "Opening Finder works on macOS only. Nothing opened.", undefined, [
+      { command: `${PRODUCT} outputs --json`, why: "Print the outputs folder to open it yourself.", audience: "agent" },
+    ]);
+  }
+  const result = await (deps.runner ?? new BunProcessRunner()).run(argv, { maxOutputBytes: 4_096 });
+  if (result.exitCode !== 0) throw new HranessError("internal", "Finder didn't open. Try again.");
+}
+
+interface OutputsListData {
+  readonly root: string;
+  readonly total: number;
+  readonly outputs: StatusOutputs["latest"];
+}
+
+interface OpenedData {
+  readonly opened: string;
+  readonly reveal: boolean;
+}
+
+// defineRegistry takes a heterogeneous verb list typed Verb<any, any>[] upstream.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function implemented(deps: RegistryDependencies): Verb<any, any>[] {
+  const stateRoot = () => stateRootOf(deps);
+  const status: Verb<Record<string, never>, number> = {
+    path: ["status"],
+    opClass: "read",
+    schema: STATUS_SCHEMA,
+    summary: "What Slopcamera is doing, credits, newest outputs and old login items",
+    output: "raw",
+    input: () => ({}),
+    async run(_input, ctx) {
+      const envelope = loadStatus(deps);
+      if (ctx.json) {
+        ctx.io.stdout.write(`${JSON.stringify(envelope)}\n`);
+      } else if (envelope.ok) {
+        ctx.io.stdout.write(renderSnapshot(statusViews(deps.now), envelope.data));
+        for (const next of envelope.next ?? []) ctx.io.stdout.write(`next: ${next.command}  (${next.why})\n`);
+      }
+      return 0;
+    },
+  };
+  const tui: Verb<{ snapshot: boolean; width?: number }, number> = {
+    path: ["tui"],
+    opClass: "read",
+    schema: STATUS_SCHEMA,
+    summary: "The status screen; --snapshot prints it once, --json prints the status",
+    flags: ["snapshot"],
+    valueFlags: ["width"],
+    usage: "[--snapshot|--json] [--width N]",
+    output: "raw",
+    input(argv) {
+      if (argv.positionals.length > 0) throw new HranessError("usage", "tui takes no arguments.");
+      const width = argv.flags.width;
+      if (width === undefined) return { snapshot: argv.flags.snapshot === true };
+      if (typeof width !== "string" || !/^[0-9]{1,4}$/u.test(width) || Number(width) < 20 || Number(width) > 400) {
+        throw new HranessError("usage", "--width takes a number of columns from 20 to 400.");
+      }
+      return { snapshot: argv.flags.snapshot === true, width: Number(width) };
+    },
+    async run(input, ctx) {
+      const mode = chooseMode(ctx.json, input.snapshot, deps.stdoutIsTerminal ?? process.stdout.isTTY === true);
+      return await runTui({
+        load: async () => loadStatus(deps),
+        views: statusViews(deps.now),
+        mode,
+        ...(input.width === undefined ? {} : { width: input.width }),
+        io: deps.tuiIo ?? { stdout: { write: (text: string) => ctx.io.stdout.write(text), ...(process.stdout.columns === undefined ? {} : { columns: process.stdout.columns }) }, stdin: process.stdin },
+      });
+    },
+  };
+  const legacyRetire: Verb<Record<string, never>, { retired: { label: string; from: string; to: string }[]; loginItem: ReturnType<typeof inspectLegacyLogin> }> = {
+    path: ["legacy", "retire"],
+    opClass: "operate",
+    schema: schemaFor(["legacy", "retire"]),
+    summary: "Stop the old menu bar opening at login, keeping its file",
+    input(argv) {
+      if (argv.positionals.length > 0) throw new HranessError("usage", "legacy retire takes no arguments.");
+      return {};
+    },
+    async run() {
+      if (deps.platform !== "darwin") return { retired: [], loginItem: { state: "none" } };
+      const retired = await retireLegacyLogin(deps.env.HOME, deps.retire ?? {});
+      return { retired, loginItem: inspectLegacyLogin(deps.env.HOME) };
+    },
+    text(output) {
+      const moved = output.retired.map(item => `Moved ${item.from} to ${item.to}. The old menu bar no longer opens at login.`);
+      if (output.loginItem.state === "not-ours") moved.push("A menu bar login item was changed outside Slopcamera, so it was left alone.");
+      return moved.length === 0 ? "Nothing to retire. The old menu bar doesn't open at login." : moved.join("\n");
+    },
+  };
+  const outputsList: Verb<Record<string, never>, OutputsListData> = {
+    path: ["outputs", "list"],
+    opClass: "read",
+    schema: schemaFor(["outputs", "list"]),
+    summary: "List the files in the outputs folder, newest first",
+    input(argv) {
+      if (argv.positionals.length > 0) throw new HranessError("usage", "outputs list takes no arguments.");
+      return {};
+    },
+    async run() {
+      const listed = listOutputs(outputsDirectory(stateRoot()), OUTPUTS_LIST_LIMIT);
+      return { root: listed.root, total: listed.total, outputs: listed.latest };
+    },
+    text(output) {
+      if (output.outputs.length === 0) return `No outputs yet in ${output.root}`;
+      return output.outputs.map(item => `${item.name}\t${item.bytes}\t${item.modifiedAt}`).join("\n");
+    },
+  };
+  const openVerb = (reveal: boolean): Verb<{ name?: string }, OpenedData> => ({
+    path: ["outputs", reveal ? "reveal" : "open"],
+    opClass: "operate",
+    schema: schemaFor(["outputs", reveal ? "reveal" : "open"]),
+    summary: reveal ? "Show one output in Finder" : "Open the outputs folder, or one output, on this Mac",
+    usage: reveal ? "<name>" : "[<name>]",
+    input(argv) {
+      if (argv.positionals.length > 1) throw new HranessError("usage", "Name at most one output.");
+      const name = argv.positionals[0];
+      if (reveal && name === undefined) throw new HranessError("usage", "Name the output to show, as `slopcamera outputs list` prints it.");
+      return name === undefined ? {} : { name };
+    },
+    async run(input) {
+      const root = outputsDirectory(stateRoot());
+      if (input.name === undefined) {
+        let folder = false;
+        try {
+          folder = lstatSync(root).isDirectory();
+        } catch {
+          folder = false;
+        }
+        if (!folder) {
+          throw new HranessError("not-found", "There's no outputs folder yet. Agents create it when they save their first output.", undefined, [
+            { command: `${PRODUCT} outputs --json`, why: "Create the outputs folder and print its path.", audience: "agent" },
+          ]);
+        }
+        await finder(deps, ["/usr/bin/open", "--", root]);
+        return { opened: root, reveal: false };
+      }
+      const path = outputPath(root, input.name);
+      await finder(deps, reveal ? ["/usr/bin/open", "-R", "--", path] : ["/usr/bin/open", "--", path]);
+      return { opened: path, reveal };
+    },
+    text(output) {
+      return output.reveal ? `Showed ${output.opened} in Finder.` : `Opened ${output.opened}.`;
+    },
+  });
+  return [status, tui, legacyRetire, outputsList, openVerb(false), openVerb(true)];
+}
+
+/** A verb `args.ts` parses and runs; the registry only lists it. */
+function listed(row: VerbRow): Verb<unknown, unknown> {
+  return {
+    path: row.path,
+    opClass: row.opClass,
+    schema: schemaFor(row.path),
+    summary: row.summary,
+    input: () => {
+      throw new HranessError("internal", `slopcamera ${row.path.join(" ")} is run by the main parser.`);
+    },
+    run: async () => undefined,
+  };
+}
+
+/** The shared envelope codes a Slopcamera error keeps as is. */
+const SHARED_CODES = new Set<ErrorCode>(["usage", "not-found", "conflict", "internal"]);
+
+/**
+ * Answers a Slopcamera application error with a declared envelope code: the
+ * shared code when there is one, otherwise `slopcamera.<code>`. Without this
+ * the registry reports every such error as an unexpected internal failure.
+ */
+export function asHranessError(error: unknown): unknown {
+  if (!(error instanceof CliError)) return error;
+  const shared = error.code as ErrorCode;
+  const code: ErrorCode = SHARED_CODES.has(shared) ? shared : `${PRODUCT}.${error.code}`;
+  return new HranessError(code, error.message);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function withDeclaredErrors(verb: Verb<any, any>): Verb<any, any> {
+  return {
+    ...verb,
+    input(argv) {
+      try {
+        return verb.input(argv);
+      } catch (error) {
+        throw asHranessError(error);
+      }
+    },
+    async run(input, ctx) {
+      try {
+        return await verb.run(input, ctx);
+      } catch (error) {
+        throw asHranessError(error);
+      }
+    },
+  };
+}
+
+export function slopcameraRegistry(deps: RegistryDependencies): Registry {
+  const own = implemented(deps).map(withDeclaredErrors);
+  const ownPaths = new Set(own.map(verb => verb.path.join(" ")));
+  return defineRegistry(PRODUCT, [
+    ...own,
+    ...CLI_VERBS.filter(row => !ownPaths.has(row.path.join(" "))).map(listed),
+  ]);
+}
+
+/** Runs a registry command line and returns its exit status. */
+export async function runRegistry(argv: readonly string[], io: CliIO, deps: RegistryDependencies): Promise<number> {
+  return await runRegistryCli(slopcameraRegistry(deps), argv, io);
+}
+
+export { okEnvelope };