@hraness/slopcamera 3.2.6 → 3.2.8

package/apps/desktop/cli/media-ingest-program.ts

@@ -67,7 +67,7 @@ function removeStagedImport(
   }));
 }
 
-function stageImport(projectDirectory: string, sourcePath: string): Program<StagedMediaImport> {
+function stageImport(projectDirectory: string, sourcePath: string, maximumBytes: number): Program<StagedMediaImport> {
   return Effect.gen(function*() {
     const platform = yield* MediaIngestPlatform;
     const source = yield* platform.sourcePath(sourcePath);
@@ -78,8 +78,8 @@ function stageImport(projectDirectory: string, sourcePath: string): Program<Stag
       if (before.isSymbolicLink() || !before.isFile()) {
         throw new CliError("unsafe-path", `Media source must be a physical regular file: ${sourcePath}`);
       }
-      if (before.size <= 0 || before.size > MAX_MEDIA_BYTES) {
-        throw new CliError("invalid-data", `Media source must contain 1 through ${MAX_MEDIA_BYTES} bytes.`);
+      if (before.size <= 0 || before.size > maximumBytes) {
+        throw new CliError("invalid-data", `Media source must contain 1 through ${maximumBytes} bytes.`);
       }
     });
     const imports = yield* privateImportsDirectory(projectDirectory);
@@ -178,6 +178,11 @@ function commitImport(imported: StagedMediaImport): Program<boolean> {
 export function ingestProjectMediaProgram(options: IngestProjectMediaOptions): Program<IngestedProjectMedia> {
   return Effect.gen(function*() {
     const platform = yield* MediaIngestPlatform;
+    const maximumBytes = yield* operationValidation("media", () => {
+      const bound = options.maximumBytes ?? MAX_MEDIA_BYTES;
+      if (!Number.isSafeInteger(bound) || bound < 1 || bound > MAX_MEDIA_BYTES) throw new CliError("invalid-data", "Invalid media import byte bound.");
+      return bound;
+    });
     const role = yield* operationValidation("media", () => ProjectAssetRoleSchema.parse(options.role));
     const [repositoryRoot, projectDirectory] = yield* Effect.all([
       platform.realpath(options.repositoryRoot), platform.realpath(options.projectDirectory),
@@ -186,7 +191,7 @@ export function ingestProjectMediaProgram(options: IngestProjectMediaOptions): P
     })));
     yield* platform.assertWithin(repositoryRoot, projectDirectory, "Project media import directory is outside the repository.");
     return yield* operationResource(
-      stageImport(projectDirectory, options.sourcePath),
+      stageImport(projectDirectory, options.sourcePath, maximumBytes),
       imported => Effect.gen(function*() {
         const probe = yield* probeProjectMediaProgram(options.ffprobe, options.runner, imported.temporaryPath);
         const location = yield* platform.assetLocation(repositoryRoot, imported.absolutePath, options.sourcePath);

package/apps/desktop/cli/menubar.ts

@@ -0,0 +1,244 @@
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import type { Stats } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { CliError } from "./errors";
+import type { CliIo } from "./io";
+import { writeJson, writeLine } from "./io";
+import { ensurePrivateDirectory } from "./paths";
+
+const SETTLE_MS = 400;
+const LABEL = "com.hraness.slopcamera.menubar";
+
+function xml(value: string): string { return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;"); }
+function exists(path: string): boolean { try { const info = lstatSync(path); return isAbsolute(path) && realpathSync(path) === resolve(path) && (info.uid === process.getuid?.() || info.uid === 0) && info.isFile() && (info.mode & 0o111) !== 0 && (info.mode & 0o022) === 0; } catch { return false; } }
+
+/** The directory agents write user-facing outputs into. */
+export function outputsRoot(stateRoot: string): string {
+  const productRoot = stateRoot.endsWith(`${sep}cli`) ? dirname(stateRoot) : stateRoot;
+  return join(productRoot, "outputs");
+}
+export function resolveMenubarBinary(repositoryRoot: string, environment: Readonly<Record<string, string | undefined>> = process.env): string | null {
+  const explicit = environment.SLOPCAMERA_MENUBAR;
+  if (explicit !== undefined) return explicit !== "" && exists(explicit) ? explicit : null;
+  const candidates = [ resolve(dirname(process.execPath), "slopcamera-menubar"), ...(environment.HOME === undefined || environment.HOME === "" ? [] : [installedBinaryPath(environment)]), resolve(repositoryRoot, "desktop", "target", "release", "slopcamera-menubar")];
+  for (const candidate of candidates) if (candidate !== undefined && candidate !== "" && exists(candidate)) return candidate;
+  return null;
+}
+export function launchAgentPath(environment: Readonly<Record<string, string | undefined>> = process.env): string {
+  const home = environment.HOME; if (home === undefined || home === "" || !isAbsolute(home)) throw new CliError("unavailable", "HOME is required for a per-user LaunchAgent.");
+  return join(home, "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+export function installedBinaryPath(environment: Readonly<Record<string, string | undefined>> = process.env): string {
+  const home = environment.HOME; if (home === undefined || home === "" || !isAbsolute(home)) throw new CliError("unavailable", "HOME is required for a per-user menu-bar install.");
+  return join(home, "Library", "Application Support", "Slopcamera", "menubar", "slopcamera-menubar");
+}
+export function launchAgentPlist(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(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`;
+}
+type Environment = Readonly<Record<string, string | undefined>>;
+const MAX_BINARY_BYTES = 128 * 1024 * 1024;
+
+function infoAt(path: string): Stats | null {
+  try { return lstatSync(path); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/** Existing shared directories retain their permissions; links are never followed. */
+function checkParents(path: string, environment: Environment, create = false): void {
+  const home = environment.HOME;
+  if (!home || !isAbsolute(home) || realpathSync(home) !== resolve(home)) {
+    throw new CliError("unsafe-path", "HOME must be an absolute physical directory.");
+  }
+  const suffix = relative(home, dirname(path));
+  if (suffix.startsWith(`..${sep}`) || suffix === ".." || isAbsolute(suffix)) {
+    throw new CliError("unsafe-path", "The menu-bar install must remain under HOME.");
+  }
+  let cursor = home;
+  for (const part of ["", ...suffix.split(sep)]) {
+    if (part) cursor = join(cursor, part);
+    let info = infoAt(cursor);
+    if (info === null) {
+      if (!create) return;
+      mkdirSync(cursor, { mode: 0o700 });
+      info = lstatSync(cursor);
+    }
+    if (!info.isDirectory() || info.uid !== process.getuid?.() || (info.mode & 0o022) !== 0) {
+      throw new CliError("unsafe-path", "Menu-bar install directories must be owned physical directories without shared write access.");
+    }
+  }
+}
+
+function assertOwnedFile(path: string): void {
+  const info = infoAt(path);
+  if (info !== null && (!info.isFile() || info.nlink !== 1 || info.uid !== process.getuid?.() || (info.mode & 0o022) !== 0)) {
+    throw new CliError("unsafe-path", "The menu-bar install contains an unsafe file.");
+  }
+}
+
+function readRegular(path: string, maximum: number, executable = false): Buffer {
+  if (!isAbsolute(path) || realpathSync(path) !== resolve(path) || Buffer.byteLength(path) > 4096 || /[\u0000-\u001f\u007f{}"\\]/u.test(path)) {
+    throw new CliError("unsafe-path", "The menu-bar file must have a bounded physical absolute path.");
+  }
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const info = fstatSync(fd);
+    if (!info.isFile() || (info.uid !== process.getuid?.() && info.uid !== 0) || info.size > maximum || info.size === 0 || (info.mode & 0o022) !== 0 || (executable && (info.mode & 0o111) === 0)) {
+      throw new CliError("unsafe-path", "The menu-bar file must be bounded, regular, and protected from shared writes.");
+    }
+    const bytes = Buffer.alloc(info.size + 1);
+    let count = 0;
+    while (count < bytes.length) {
+      const read = readSync(fd, bytes, count, bytes.length - count, count);
+      if (read === 0) break;
+      count += read;
+    }
+    const after = fstatSync(fd);
+    if (count !== info.size || after.size !== info.size || after.mtimeMs !== info.mtimeMs || after.ctimeMs !== info.ctimeMs) {
+      throw new CliError("conflict", "The menu-bar file changed while it was being read.");
+    }
+    return bytes.subarray(0, count);
+  } finally { closeSync(fd); }
+}
+
+function readAgent(path: string, environment: Environment): string | null {
+  checkParents(path, environment);
+  if (infoAt(path) === null) return null;
+  assertOwnedFile(path);
+  return readRegular(path, 16 * 1024).toString("utf8");
+}
+
+/** Configuration state only; it does not claim the launchd service is running. */
+export type LaunchAgentState = "absent" | "installed" | "conflict";
+export type LaunchctlRunner = (args: readonly string[], allowMissing?: boolean) => string | null;
+function launchctl(args: readonly string[], allowMissing = false): string | null {
+  const uid = process.getuid?.();
+  if (uid === undefined) throw new CliError("unavailable", "The current user has no launchd GUI domain.");
+  const result = Bun.spawnSync(["/bin/launchctl", ...args.map((arg) => arg.replaceAll("{uid}", String(uid)))], { stdin: "ignore", stdout: "pipe", stderr: "pipe", timeout: 10_000, maxBuffer: 64 * 1024 });
+  return interpretLaunchctlResult(result, uid, allowMissing);
+}
+export function interpretLaunchctlResult(result: { success: boolean; exitCode: number; stdout: Uint8Array; stderr: Uint8Array }, uid: number, allowMissing: boolean): string | null {
+  if (result.stdout.byteLength + result.stderr.byteLength > 64 * 1024) throw new CliError("unavailable", "launchctl exceeded the bounded response size.");
+  if (result.success && result.exitCode === 0) return Buffer.from(result.stdout).toString();
+  if (allowMissing && result.exitCode === 113 && result.stdout.length === 0 && Buffer.from(result.stderr).toString() === `Bad request.\nCould not find service "${LABEL}" in domain for user gui: ${uid}\n`) return null;
+  throw new CliError("unavailable", "launchctl could not reconcile the Slopcamera menu-bar LaunchAgent. Run menubar install again to retry.");
+}
+
+function loadedOwned(path: string, binary: string, current: string | null, run: LaunchctlRunner): boolean {
+  const output = run(["print", `gui/{uid}/${LABEL}`], true);
+  if (output === null) return false;
+  const uid = process.getuid?.();
+  if (current === null || Buffer.byteLength(output) > 64 * 1024 || !output.startsWith(`gui/${uid}/${LABEL} = {\n`)) {
+    throw new CliError("conflict", "The loaded menu-bar service has an unverified identity.");
+  }
+  const lines = output.split("\n").map(line => line.trim());
+  const field = (key: string): string | null => {
+    const values = lines.filter(line => line.startsWith(`${key} = `));
+    return values.length === 1 ? values[0]!.slice(key.length + 3) : null;
+  };
+  const argumentsStart = lines.indexOf("arguments = {");
+  const argumentsEnd = lines.indexOf("}", argumentsStart + 1);
+  if (field("path") !== path || field("program") !== binary || argumentsStart < 0 || argumentsEnd !== argumentsStart + 2 || lines[argumentsStart + 1] !== binary) {
+    throw new CliError("conflict", "The loaded menu-bar service does not match this install; it was left untouched.");
+  }
+  return true;
+}
+export function launchAgentState(binary: string, environment: Environment = process.env): LaunchAgentState {
+  const content = readAgent(launchAgentPath(environment), environment);
+  if (content === null) return "absent";
+  checkParents(binary, environment);
+  assertOwnedFile(binary);
+  return content === launchAgentPlist(binary) && exists(binary) ? "installed" : "conflict";
+}
+function assertMac(platform: NodeJS.Platform): void {
+  if (platform !== "darwin") throw new CliError("unsupported-plan", "Slopcamera menu-bar LaunchAgents are supported only on macOS.");
+}
+export function installLaunchAgent(binary: string, environment: Environment = process.env, platform: NodeJS.Platform = process.platform, runLaunchctl: LaunchctlRunner = launchctl): LaunchAgentState {
+  assertMac(platform);
+  if (!isAbsolute(binary)) throw new CliError("unsafe-path", "LaunchAgent binary must be an absolute path.");
+  const stable = installedBinaryPath(environment);
+  const path = launchAgentPath(environment);
+  const current = readAgent(path, environment);
+  const expected = launchAgentPlist(stable);
+  checkParents(stable, environment);
+  assertOwnedFile(stable);
+  if (current !== null && current !== expected || current === null && infoAt(stable) !== null) {
+    throw new CliError("conflict", "The existing Slopcamera menu-bar install is not owned by this command.");
+  }
+  const bytes = readRegular(binary, MAX_BINARY_BYTES, true);
+  loadedOwned(path, stable, current, runLaunchctl);
+  checkParents(path, environment, true);
+  checkParents(stable, environment, true);
+  // Unique private staging directories prevent predictable temporary-file clobbering.
+  const binaryStage = mkdtempSync(join(dirname(stable), ".install-"));
+  let agentStage: string | undefined;
+  try {
+    agentStage = mkdtempSync(join(dirname(path), ".slopcamera-install-"));
+    const stagedBinary = join(binaryStage, "binary");
+    const stagedAgent = join(agentStage, "agent.plist");
+    writeFileSync(stagedBinary, bytes, { mode: 0o700, flag: "wx" });
+    writeFileSync(stagedAgent, expected, { mode: 0o600, flag: "wx" });
+    if (readAgent(path, environment) !== current) throw new CliError("conflict", "The menu-bar install changed concurrently.");
+    assertOwnedFile(stable);
+    // Retry bootstrap even when the plist matches: a previous bootstrap may have failed.
+    if (loadedOwned(path, stable, current, runLaunchctl)) runLaunchctl(["bootout", `gui/{uid}/${LABEL}`], true);
+    renameSync(stagedBinary, stable);
+    renameSync(stagedAgent, path);
+    runLaunchctl(["bootstrap", "gui/{uid}", path]);
+    return "installed";
+  } finally {
+    rmSync(binaryStage, { recursive: true });
+    if (agentStage !== undefined) rmSync(agentStage, { recursive: true });
+  }
+}
+export function uninstallLaunchAgent(_binary: string, environment: Environment = process.env, platform: NodeJS.Platform = process.platform, runLaunchctl: LaunchctlRunner = launchctl): LaunchAgentState {
+  assertMac(platform);
+  const stable = installedBinaryPath(environment);
+  const path = launchAgentPath(environment);
+  const current = readAgent(path, environment);
+  if (current === null) return "absent";
+  if (current !== launchAgentPlist(stable)) throw new CliError("conflict", "The existing Slopcamera menu-bar LaunchAgent is not owned by this command.");
+  checkParents(stable, environment);
+  assertOwnedFile(stable);
+  if (loadedOwned(path, stable, current, runLaunchctl)) runLaunchctl(["bootout", `gui/{uid}/${LABEL}`], true);
+  if (readAgent(path, environment) !== current) throw new CliError("conflict", "The menu-bar install changed concurrently.");
+  assertOwnedFile(stable);
+  rmSync(path);
+  if (infoAt(stable) !== null) rmSync(stable);
+  return "absent";
+}
+async function runBinary(binary: string, foreground: boolean): Promise<number> {
+  let child: Bun.Subprocess;
+  try { child = Bun.spawn([binary], foreground ? { stdin: "inherit", stdout: "inherit", stderr: "inherit" } : { stdin: "ignore", stdout: "ignore", stderr: "ignore" }); } catch { throw new CliError("unavailable", "The Slopcamera menu bar could not start."); }
+  if (!foreground) { child.unref(); const settled = await Promise.race([child.exited.then((code) => code as number | null), Bun.sleep(SETTLE_MS).then(() => null)]); if (settled !== null) throw new CliError("unavailable", "The Slopcamera menu bar exited during startup."); return 0; }
+  return await child.exited;
+}
+export async function launchMenubar(io: CliIo, repositoryRoot: string, asJson: boolean, mode: "foreground" | "background" = "foreground"): Promise<void> {
+  const binary = resolveMenubarBinary(repositoryRoot, io.env);
+  if (binary === null) throw new CliError("unavailable", "The Slopcamera menu bar is not installed. Build it separately or set SLOPCAMERA_MENUBAR.");
+  const code = await runBinary(binary, mode === "foreground");
+  if (code !== 0) throw new CliError("unavailable", "The Slopcamera menu bar exited during startup.");
+  if (asJson) writeJson(io, { running: mode === "background", foreground: mode === "foreground" });
+  else writeLine(io, mode === "foreground" ? "Slopcamera menu bar exited." : "Slopcamera menu bar is running.");
+}
+export async function manageMenubar(io: CliIo, repositoryRoot: string, action: "install" | "uninstall" | "status", asJson: boolean): Promise<void> {
+  assertMac(io.platform);
+  const stable = installedBinaryPath(io.env);
+  let state: LaunchAgentState;
+  if (action === "install") {
+    const binary = resolveMenubarBinary(repositoryRoot, io.env);
+    if (binary === null) throw new CliError("unavailable", "The Slopcamera menu bar is not installed. Build it separately or set SLOPCAMERA_MENUBAR.");
+    state = installLaunchAgent(binary, io.env, io.platform);
+  } else {
+    state = action === "uninstall" ? uninstallLaunchAgent(stable, io.env, io.platform) : launchAgentState(stable, io.env);
+  }
+  if (asJson) writeJson(io, { launchAgent: state });
+  else writeLine(io, `Slopcamera menu-bar LaunchAgent: ${state}.`);
+}
+export async function reportOutputsRoot(io: CliIo, stateRoot: string, asJson: boolean): Promise<void> {
+  const directory = outputsRoot(stateRoot);
+  await ensurePrivateDirectory(directory);
+  if (asJson) writeJson(io, { outputs: directory });
+  else writeLine(io, directory);
+}

package/apps/desktop/cli/music-analysis-service.ts

@@ -15,18 +15,25 @@ import {
 } from "../contracts";
 import {
   analyzeMusic,
+  analyzeAudioReactivity,
+  AUDIO_REACTIVITY_MAX_DURATION_US,
+  AUDIO_REACTIVITY_SAMPLE_RATE_HZ,
   canonicalSlopcameraPersistenceDocument,
   canonicalJson,
   canonicalJsonSha256,
+  createNodeBundleFileSystem,
   saveAnalysisArtifact,
   saveVideoProject,
   sha256Hex,
   type MonoPcm,
 } from "../core";
+import { HtmlOverlayAudioReactivitySchema } from "../html-overlay/audio-reactivity";
 import { decodeAlignmentPcm, resolveAudioAnalysisSubject } from "./audio-analysis";
 import { CliError } from "./errors";
 import type { ProcessRunner } from "./io";
+import { SELF_CONTAINED_MEDIA_INPUT_ARGUMENTS } from "./media-ingest-model";
 import { ensurePhysicalPrivateDirectoryWithin } from "./paths";
+import { resolveVerifiedProjectMedia, type PhysicalProjectMediaFingerprint } from "./project-media-integrity";
 import { projectAnalysisPath, type OpenProject } from "./project-service";
 
 export const MUSIC_ANALYSIS_SAMPLE_RATE_HZ = 8_000;
@@ -174,6 +181,60 @@ export async function readMonoFloat32PcmBounded(
   }
 }
 
+const MAX_AUDIO_REACTIVITY_PCM_BYTES = 600 * AUDIO_REACTIVITY_SAMPLE_RATE_HZ * 4;
+
+/** Decode one verified retained soundtrack prefix for the optional bands-v1 sidecar. */
+export async function analyzeRetainedAudioReactivity(options: {
+  readonly repositoryRoot: string;
+  readonly jobDirectory: string;
+  readonly audio: PhysicalProjectMediaFingerprint;
+  readonly durationUs: number;
+  readonly streamIndex: number;
+  readonly ffmpeg: string;
+  readonly run: (argv: readonly [string, ...string[]]) => Promise<unknown>;
+  readonly fence: () => Promise<void>;
+}) {
+  if (!Number.isSafeInteger(options.durationUs) || options.durationUs < 1
+    || options.durationUs > AUDIO_REACTIVITY_MAX_DURATION_US
+    || !Number.isSafeInteger(options.streamIndex) || options.streamIndex < 0) {
+    throw new CliError("invalid-data", "Audio reactivity duration or stream index is outside its bound.");
+  }
+  const verify = async () => {
+    await options.fence();
+    return await resolveVerifiedProjectMedia({ repositoryRoot: options.repositoryRoot,
+      path: options.audio.path, expected: options.audio, label: "Audio reactivity soundtrack" });
+  };
+  const source = await verify();
+  const pcmPath = join(options.jobDirectory, "audio-reactivity.f32le");
+  const fs = createNodeBundleFileSystem(options.jobDirectory);
+  try {
+    await options.run([options.ffmpeg, "-nostdin", "-v", "error", "-n", "-threads", "2",
+      ...SELF_CONTAINED_MEDIA_INPUT_ARGUMENTS, "-i", source, "-map", `0:${options.streamIndex}`,
+      "-vn", "-sn", "-dn", "-t", (options.durationUs / 1_000_000).toFixed(6),
+      "-ac", "1", "-ar", String(AUDIO_REACTIVITY_SAMPLE_RATE_HZ), "-c:a", "pcm_f32le", "-f", "f32le",
+      "-fs", String(MAX_AUDIO_REACTIVITY_PCM_BYTES + 4), pcmPath]);
+    await verify();
+    const before = await fs.inspectFile!("audio-reactivity.f32le", MAX_AUDIO_REACTIVITY_PCM_BYTES);
+    const pcm = await readMonoFloat32PcmBounded(pcmPath, { maxBytes: MAX_AUDIO_REACTIVITY_PCM_BYTES, sampleRateHz: AUDIO_REACTIVITY_SAMPLE_RATE_HZ });
+    const expectedSamples = Math.round(options.durationUs * AUDIO_REACTIVITY_SAMPLE_RATE_HZ / 1_000_000);
+    if (Math.abs(pcm.samples.length - expectedSamples) > 2) {
+      throw new CliError("invalid-data", "Audio reactivity decode did not cover the requested soundtrack prefix.");
+    }
+    const analysis = analyzeAudioReactivity(pcm);
+    await options.fence();
+    const after = await fs.inspectFile!("audio-reactivity.f32le", MAX_AUDIO_REACTIVITY_PCM_BYTES);
+    if (before.bytes !== after.bytes || before.sha256 !== after.sha256) {
+      throw new CliError("conflict", "Audio reactivity PCM changed during analysis.");
+    }
+    return HtmlOverlayAudioReactivitySchema.parse({ kind: "slopcamera.audio-reactivity", schemaVersion: 1,
+      profile: "bands-v1", rateHz: 60, ...analysis,
+      source: { bytes: options.audio.bytes, sha256: options.audio.sha256 },
+      pcm: { sampleCount: pcm.samples.length, sha256: before.sha256 } });
+  } finally {
+    await rm(pcmPath, { force: true });
+  }
+}
+
 export interface WithDecodedMusicPcmOptions {
   readonly ffmpeg: string;
   readonly maxDecodedPcmBytes?: number;

package/apps/desktop/cli/portable-surface.ts

@@ -1,3 +1,5 @@
+import { reportUsefulResult, type UsefulResultObserver } from "../../../src/support-completion";
+
 import { constants } from "node:fs";
 import { mkdir, open } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
@@ -16,7 +18,10 @@ import { CliError } from "./errors";
 
 const HEADLESS_SLOPCAMERA_CLI_MODULE = "@hraness/slopcamera/cli";
 
-async function runHeadlessSlopcameraCli(argv: readonly string[]): Promise<void> {
+async function runHeadlessSlopcameraCli(
+  argv: readonly string[],
+  options?: Readonly<{ onUsefulResult?: UsefulResultObserver }>,
+): Promise<void> {
   // Keep this as a runtime package import so the headless CLI retains its own
   // package-relative skill and asset resolution inside an installed bundle.
   const module: unknown = await import(HEADLESS_SLOPCAMERA_CLI_MODULE);
@@ -28,13 +33,14 @@ async function runHeadlessSlopcameraCli(argv: readonly string[]): Promise<void>
   ) {
     throw new CliError("unavailable", "The portable Slopcamera CLI is unavailable.");
   }
-  await module.main(argv);
+  await module.main(argv, options);
 }
 
 export interface PortableSurfaceDependencies {
+  readonly onUsefulResult?: UsefulResultObserver;
   readonly cwd?: () => string;
   readonly log?: (value: string) => void;
-  readonly runHeadless?: (argv: readonly string[]) => Promise<void>;
+  readonly runHeadless?: (argv: readonly string[], options?: Readonly<{ onUsefulResult?: UsefulResultObserver }>) => Promise<void>;
   readonly writeScaffold?: (path: string, html: string) => Promise<void>;
 }
 function optionValue(argv: readonly string[], name: string): string | undefined {
@@ -187,6 +193,7 @@ async function runHtmlScaffold(
     createHtmlOverlayScaffold(kind),
   );
   (dependencies.log ?? console.log)(`Created ${outputPath}`);
+  reportUsefulResult(dependencies.onUsefulResult);
   return 0;
 }
 
@@ -214,6 +221,7 @@ export async function runPortableSurface(
 ): Promise<number | undefined> {
   const argv = canonicalizeUnifiedCliArgs(argvInput);
   if (argv[0] === "html") {
+    if (argv[1] === "render" || argv.includes("--help") || argv.includes("-h")) return undefined;
     if (argv[1] === "catalog") return runHtmlCatalog(argv, dependencies);
     return await runHtmlScaffold(argv, dependencies);
   }
@@ -234,7 +242,8 @@ export async function runPortableSurface(
   const previousExitCode = process.exitCode;
   process.exitCode = undefined;
   try {
-    await (dependencies.runHeadless ?? runHeadlessSlopcameraCli)(argv);
+    await (dependencies.runHeadless ?? runHeadlessSlopcameraCli)(argv,
+      dependencies.onUsefulResult === undefined ? {} : { onUsefulResult: dependencies.onUsefulResult });
     return process.exitCode ?? 0;
   } finally {
     process.exitCode = previousExitCode;

package/apps/desktop/cli/root-help-intro.ts

@@ -0,0 +1,14 @@
+const camera = "   __\n _|__|_\n|  (o) |\n|______|\n\n";
+
+/** Decoration is confined to readable, interactive root help. */
+export function rootHelpIntro(
+  argv: readonly string[],
+  terminal: Readonly<{ isTTY: boolean; term: string | undefined; columns: number | undefined }>,
+): string {
+  return terminal.isTTY && terminal.term !== "dumb"
+    && terminal.columns !== undefined && Number.isFinite(terminal.columns) && terminal.columns >= 48
+    && (argv.length === 0
+      || argv.length === 1 && (argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h"))
+    ? camera
+    : "";
+}

package/apps/desktop/code/application-node-planner.ts

@@ -51,7 +51,6 @@ import {
   bindProjectRenderInputV2,
   bindProjectRenderInputV3,
   bindProjectRenderToolchain,
-  parseRecordingOperationOutput,
   projectEditCommitReceipt,
   projectEditTransactionId,
   reconcileVariantSelectionPromotion,
@@ -105,7 +104,6 @@ import type {
 import { workflowBoundary, workflowValidation, type WorkflowFailure } from "./workflow-effects";
 
 const ANALYSIS_ID_DOMAIN = "studio.workflow.analysis-id/v1";
-type RecordingOperationKind = Extract<OperationKind, `recording.${string}`>;
 type GatewayOperationKind = Extract<OperationKind, `gateway.${string}`>;
 
 export const APPLICATION_VERIFIED_RECEIPT_RECONCILER_KINDS =
@@ -114,15 +112,6 @@ export const APPLICATION_VERIFIED_RECEIPT_RECONCILER_KINDS =
     "render.project",
   ] as const satisfies readonly OperationKind[]);
 
-function isRecordingOperationKind(
-  kind: OperationKind,
-): kind is RecordingOperationKind {
-  return kind === "recording.start"
-    || kind === "recording.pause"
-    || kind === "recording.resume"
-    || kind === "recording.stop";
-}
-
 function isGatewayOperationKind(
   kind: OperationKind,
 ): kind is GatewayOperationKind {
@@ -934,36 +923,6 @@ function renderNodeReconciliation(result: ProjectRenderReconciliation | Awaited<
   };
 }
 
-async function reconcileRecordingNode(
-  application: ApplicationContext,
-  operationKind: RecordingOperationKind,
-): Promise<NodeReconciliation> {
-  const controller = application.recordingController;
-  if (controller === undefined) {
-    return {
-      kind: "ambiguous",
-      message: "Recording controller is unavailable for live-state reconciliation.",
-    };
-  }
-  let output;
-  try {
-    output = parseRecordingOperationOutput(await controller.status());
-  } catch (error) {
-    return {
-      kind: "ambiguous",
-      message: error instanceof Error
-        ? `Recording state could not be reconciled: ${error.message}`
-        : "Recording state could not be reconciled.",
-    };
-  }
-  return {
-    kind: "ambiguous",
-    message: `Current controller state ${output.state} for ${
-      output.recordingId ?? "no active recording"
-    } is not an exact receipt proving ${operationKind} completed; issue a new explicit action.`,
-  };
-}
-
 async function reconcileGatewayNode(
   application: ApplicationContext,
   request: NodeReconciliationRequest,
@@ -1223,12 +1182,6 @@ async function reconcileApplicationNode(
       request.operation.kind,
     );
   }
-  if (isRecordingOperationKind(request.operation.kind)) {
-    return await reconcileRecordingNode(
-      application,
-      request.operation.kind,
-    );
-  }
   if (request.operation.kind === "project.commit-edits") {
     return await reconcileProjectCommit(application, request);
   }

package/apps/desktop/code/host-source-layout.ts

@@ -0,0 +1,46 @@
+import { basename, dirname, join, resolve } from "node:path";
+
+export interface HostSourceRoots {
+  /**
+   * True when the running module is inside the committed bundle at
+   * apps/desktop/dist/cli. A bundled host still spawns the checked TypeScript
+   * sources below apps/desktop and src/.
+   */
+  readonly bundled: boolean;
+  /** The installed apps/desktop source directory. */
+  readonly desktopRoot: string;
+  /** The checkout or package root containing src/, packages/, and package.json. */
+  readonly repositoryRoot: string;
+}
+
+/**
+ * Walks to the apps/desktop anchor instead of assuming a fixed module depth.
+ * From a checkout, caller modules sit below apps/desktop/<area>/; inside the
+ * committed bundle they all share apps/desktop/dist/cli.
+ */
+export function hostSourceRoots(moduleDirectory: string): HostSourceRoots {
+  const requested = resolve(moduleDirectory);
+  let candidate = requested;
+  while (true) {
+    if (basename(candidate) === "desktop" && basename(dirname(candidate)) === "apps") {
+      return {
+        bundled: requested === join(candidate, "dist", "cli"),
+        desktopRoot: candidate,
+        repositoryRoot: dirname(dirname(candidate)),
+      };
+    }
+    const parent = dirname(candidate);
+    if (parent === candidate) {
+      // Embedded compiled-binary modules and foreign callers keep the
+      // historical assumption that the module sits one level below
+      // apps/desktop.
+      const desktopRoot = resolve(requested, "..");
+      return {
+        bundled: false,
+        desktopRoot,
+        repositoryRoot: resolve(desktopRoot, "../.."),
+      };
+    }
+    candidate = parent;
+  }
+}

package/apps/desktop/code/public.ts

@@ -100,7 +100,6 @@ export {
   type ProducedVariantMatrixHandle,
   type ProducedVariantSelectionHandle,
   type ProjectSnapshotHandle,
-  type RecordingStartOptions,
   type SelectCreativeVariantOptions,
   type VariantMatrixHandle,
   type VariantSelectionHandle,