@hraness/ghostget 0.18.10 → 0.18.13

package/src/ghostget.ts

@@ -839,6 +839,7 @@ async function runCaptureCommand(
   output: Output,
   dependencies: GhostgetDependencies,
   signal?: AbortSignal,
+  onUsefulResult?: () => void,
 ): Promise<number> {
   const resolved = resolveCaptureArgumentsWithAuth(arguments_, environment);
   const unresolvedArguments = [...prefix, ...resolved.arguments];
@@ -866,16 +867,18 @@ async function runCaptureCommand(
     if (persistentPrivateCapture) {
       ensurePrivateStateDirectory(gmailOptions.outputBase, environment);
     }
-    return dependencies.gmailCaptureMain(
+    const code = await dependencies.gmailCaptureMain(
       gmailOptions,
       resolved.auth,
       environment,
       output,
     );
+    if (code === 0) onUsefulResult?.();
+    return code;
   }
   const prepared = prepareCapture(resolved, environment);
   try {
-    return await dependencies.clipMain(
+    const code = await dependencies.clipMain(
       [...prefix, ...prepared.arguments],
       environment,
       output,
@@ -888,6 +891,8 @@ async function runCaptureCommand(
       },
       prepared.runtimeOptions,
     );
+    if (code === 0 && (parsed.value.command === "capture" || parsed.value.command === "inspect")) onUsefulResult?.();
+    return code;
   } finally {
     prepared.cleanup();
   }
@@ -1972,6 +1977,7 @@ async function runCommand(
   output: Output,
   dependencies: GhostgetDependencies,
   signal?: AbortSignal,
+  onUsefulResult?: () => void,
 ): Promise<number> {
   if (arguments_.command === "help") {
     output.stdout(renderGhostgetUsage());
@@ -2031,6 +2037,7 @@ async function runCommand(
       output,
       dependencies,
       signal,
+      onUsefulResult,
     );
   }
   if (arguments_.command === "read") {
@@ -2041,12 +2048,14 @@ async function runCommand(
       output,
       dependencies,
       signal,
+      onUsefulResult,
     );
   }
   if (arguments_.command === "media") {
     const media = await dependencies.loadMediaRuntime();
     return media.runCli(arguments_.arguments, {
       io: output,
+      ...(onUsefulResult === undefined ? {} : { onUsefulResult }),
       environment,
       ...(signal === undefined ? {} : { signal }),
     });
@@ -2066,6 +2075,7 @@ async function runCommand(
     output.stdout(
       runtime.encodeApplePhotosContactEvidenceCliOutput(result, arguments_.json),
     );
+    onUsefulResult?.();
     return 0;
   }
   if (arguments_.command === "whatsapp-export-message-like-me") {
@@ -2097,6 +2107,7 @@ async function runCommand(
         output.stdout(`Manifest SHA-256: ${safe(result.bundle.manifestSha256)}\n`);
         output.stdout("Remote history completeness is not claimed. No cloud sync occurred.\n");
       }
+      onUsefulResult?.();
       return 0;
     } finally {
       admission.release();
@@ -2136,6 +2147,7 @@ async function runCommand(
         ...(signal === undefined ? {} : { signal }),
       });
       output.stdout(runtime.encodeBeeperContactInteractionExportResult(result));
+      onUsefulResult?.();
       return 0;
     } finally {
       admission.release();
@@ -2184,6 +2196,7 @@ async function runCommand(
         counts: result.manifest.counts,
       });
       print(output, summary, arguments_.json);
+      onUsefulResult?.();
       return 0;
     } finally {
       admission.release();
@@ -2218,6 +2231,7 @@ async function runCommand(
       environment,
     );
     output.stdout(exactTerminalJson(receipt));
+    if (arguments_.command === "messaging-context") onUsefulResult?.();
     return 0;
   }
   if (arguments_.command === "doctor") {
@@ -2259,7 +2273,11 @@ async function runCommand(
     }
     return 0;
   }
-  if (arguments_.command === "thread-split") return runThreadSplit(arguments_, output);
+  if (arguments_.command === "thread-split") {
+    const code = await runThreadSplit(arguments_, output);
+    if (code === 0) onUsefulResult?.();
+    return code;
+  }
   if (arguments_.command === "thread-publish") {
     return runThreadPublish(
       arguments_,
@@ -3156,6 +3174,7 @@ async function runCommand(
             });
     if (arguments_.json) output.stdout(exactTerminalJson(value));
     else print(output, value, false);
+    if (value.view?.sources.some((source) => source.coverage.state === "observed")) onUsefulResult?.();
     return 0;
   }
   if (arguments_.command === "invoke") {
@@ -3242,6 +3261,7 @@ async function runCommand(
         const view = cachedInvocationView(result);
         if (arguments_.json) output.stdout(exactTerminalJson(view));
         else print(output, view, false);
+        if (result.status === "hit") onUsefulResult?.();
         return result.status === "hit" ? 0 : 3;
       }
       const result = await dependencies.revalidatePreparedCapability(
@@ -3256,6 +3276,7 @@ async function runCommand(
       const view = revalidatedInvocationView(result);
       if (arguments_.json) output.stdout(exactTerminalJson(view));
       else print(output, view, false);
+      if (result.live.receipt.status === "succeeded" || result.live.receipt.status === "submitted") onUsefulResult?.();
       return result.live.receipt.status === "succeeded" || result.live.receipt.status === "submitted" ? 0 : result.live.receipt.status === "indeterminate" ? 5 : 3;
     }
     const stored = createAndSaveInvocationPlan(
@@ -3325,6 +3346,7 @@ async function runCommand(
         result.receiptBinding,
         environment,
       );
+      if (result.receipt.state === "submitted") onUsefulResult?.();
       return result.receipt.state === "submitted"
         ? 0
         : result.receipt.state === "indeterminate"
@@ -3342,6 +3364,7 @@ async function runCommand(
       ...(signal === undefined ? {} : { signal }),
     });
     print(output, invocationView(result), arguments_.json);
+    if (result.receipt.status === "succeeded" || result.receipt.status === "submitted") onUsefulResult?.();
     return result.receipt.status === "succeeded" || result.receipt.status === "submitted" ? 0 : result.receipt.status === "indeterminate" ? 5 : 3;
   }
   if (arguments_.command === "runs-list") {
@@ -3483,6 +3506,7 @@ export async function main(
   output: Output = defaultOutput,
   dependencyOverrides: Partial<GhostgetDependencies> = {},
   signal?: AbortSignal,
+  onUsefulResult?: () => void,
 ): Promise<number> {
   const parsed = parseGhostgetArguments(rawArguments);
   if (!parsed.ok) {
@@ -3508,13 +3532,19 @@ export async function main(
         ).registry,
       };
     }
-    return await runCommand(
+    let usefulResult = false;
+    const code = await runCommand(
       parsed.value,
       environment,
       output,
       dependencies,
       signal,
+      () => { usefulResult = true; },
     );
+    if (code === 0 && usefulResult && signal?.aborted !== true) {
+      try { void Promise.resolve(onUsefulResult?.()).catch(() => undefined); } catch { /* Optional observation cannot alter completed work. */ }
+    }
+    return code;
   } catch (error) {
     if (error instanceof LinkedDeviceLifecycleIndeterminateError) {
       const failure = {
@@ -3600,6 +3630,7 @@ type GhostgetProcessBoundaryDependencies = {
   ) => () => void;
   readonly resendSignal: (signal: NodeJS.Signals) => void;
   readonly setExitCode: (code: number) => void;
+  readonly onUsefulResult?: () => void;
 };
 
 function subscribeProcessTermination(
@@ -3631,6 +3662,7 @@ export async function runGhostgetProcess(
   overrides: Partial<GhostgetProcessBoundaryDependencies> = {},
 ): Promise<void> {
   const dependencies: GhostgetProcessBoundaryDependencies = {
+    ...(overrides.onUsefulResult === undefined ? {} : { onUsefulResult: overrides.onUsefulResult }),
     rawArguments: overrides.rawArguments ?? process.argv.slice(2),
     environment: overrides.environment ?? process.env,
     output: overrides.output ?? defaultOutput,
@@ -3667,18 +3699,25 @@ export async function runGhostgetProcess(
     );
   };
   unsubscribeTermination = dependencies.subscribeTermination(terminate);
+  let usefulResult = false;
+  let code: number | undefined;
   try {
-    dependencies.setExitCode(await dependencies.runMain(
+    code = await dependencies.runMain(
       dependencies.rawArguments,
       dependencies.environment,
       dependencies.output,
       {},
       controller.signal,
-    ));
+      () => { usefulResult = true; },
+    );
+    dependencies.setExitCode(code);
   } finally {
     terminationState.cancelFallback?.();
     unsubscribeTermination();
   }
+  if (code === 0 && usefulResult && !controller.signal.aborted) {
+    try { void Promise.resolve(dependencies.onUsefulResult?.()).catch(() => undefined); } catch { /* Keep the completed command outcome. */ }
+  }
 }
 
 if (import.meta.main) {

package/src/media/cli.ts

@@ -38,6 +38,7 @@ export interface RunCliOptions {
   readonly homeDirectory?: string;
   readonly signal?: AbortSignal;
   readonly dependencies?: MediaCliDependencies;
+  readonly onUsefulResult?: () => void;
 }
 
 const processIo: CliIo = {
@@ -163,6 +164,10 @@ export async function runCli(argv: readonly string[], options: RunCliOptions = {
   const environment = options.environment ?? process.env;
   const homeDirectory = options.homeDirectory ?? homedir();
   const dependencies = options.dependencies ?? defaultDependencies;
+  const completed = (): void => {
+    if (options.signal?.aborted === true) return;
+    try { void Promise.resolve(options.onUsefulResult?.()).catch(() => undefined); } catch { /* Observation cannot change an archive result. */ }
+  };
   const parsed = parseArgs(argv);
   if (!parsed.ok) {
     if (parsed.json) writeJson(io, "stderr", { ok: false, error: { code: "USAGE", message: parsed.message } });
@@ -191,6 +196,7 @@ export async function runCli(argv: readonly string[], options: RunCliOptions = {
     if (command.json) writeJson(io, result.ok ? "stdout" : "stderr", { ok: result.ok, verification: result });
     else if (result.ok) io.stdout(`Verified ${sanitizeTerminalText(result.assetKey ?? command.itemDirectory)}: ${String(result.checkedArtifacts)} artifacts\n`);
     else io.stderr(`ghostget media: verification failed\n${result.failures.map((failure) => `- ${redactDiagnostic(failure, { homeDirectory })}`).join("\n")}\n`);
+    if (result.ok) completed();
     return result.ok ? 0 : 8;
   }
   if (command.kind === "transcriber-setup") {
@@ -258,6 +264,7 @@ export async function runCli(argv: readonly string[], options: RunCliOptions = {
     });
     if (command.json) writeJson(io, "stdout", captureSummary(result));
     else io.stdout(humanCaptureSummary(result));
+    completed();
     return 0;
   } catch (error) {
     const secrets = [

package/src/messaging.ts

@@ -75,6 +75,8 @@ function environmentSnapshot(
       else result[key] = value;
     }
   }
+  // Package-owned SDK children never emit standalone support notices.
+  result.GHOSTGET_CLI_DEPTH = "1";
   return Object.freeze(result);
 }
 

package/src/omni-client.ts

@@ -526,6 +526,8 @@ function snapshotEnvironment(value: unknown): Readonly<Record<string, string>> {
       defineEnvironmentValue(result, key, environmentValue);
     }
   }
+  // Package-owned SDK children never emit standalone support notices.
+  result.GHOSTGET_CLI_DEPTH = "1";
   if (value === undefined) return Object.freeze(result);
   const overrides = record(value, "Ghostget omni client environment");
   for (const [key, environmentValue] of Object.entries(overrides)) {
@@ -541,6 +543,7 @@ function snapshotEnvironment(value: unknown): Readonly<Record<string, string>> {
       defineEnvironmentValue(result, name, environmentValue);
     }
   }
+  result.GHOSTGET_CLI_DEPTH = "1";
   return Object.freeze(result);
 }
 

package/src/providers/imessage-direct-runtime.ts

@@ -448,18 +448,38 @@ export async function runImsgRpc(
   let timedOut = false;
   let cancelled = false;
   let forceKill: ReturnType<typeof setTimeout> | null = null;
+  let groupTerminated: Promise<boolean> | null = null;
   let terminationStarted = false;
   const signalGroup = (signal: "SIGTERM" | "SIGKILL"): void => {
     try {
       process.kill(-child.pid, signal);
     } catch {
-      // child.exited remains the reaping proof.
+      // The bounded group probe below establishes descendant cleanup.
     }
   };
   const terminate = (): void => {
     if (!terminationStarted) {
       terminationStarted = true;
       signalGroup("SIGTERM");
+      groupTerminated = (async (): Promise<boolean> => {
+        // A joined leader and closed pipes do not prove its descendants exited.
+        // Retain the one-second escalation, then bound final group reaping.
+        const deadline = performance.now() + 1_500;
+        for (;;) {
+          try {
+            process.kill(-child.pid, 0);
+          } catch (error) {
+            const code = typeof error === "object" && error !== null
+              && "code" in error ? error.code : undefined;
+            if (code === "ESRCH") return true;
+            // Allow a transient permission denial to settle within the same
+            // bound; it is never proof that the group exited.
+            if (code !== "EPERM") return false;
+          }
+          if (performance.now() >= deadline) return false;
+          await new Promise<void>((resolve) => setTimeout(resolve, 20));
+        }
+      })();
     }
     forceKill ??= setTimeout(() => signalGroup("SIGKILL"), 1_000);
   };
@@ -509,8 +529,14 @@ export async function runImsgRpc(
     });
   } finally {
     clearTimeout(timeout);
-    if (forceKill !== null) clearTimeout(forceKill);
     invocation.signal?.removeEventListener("abort", onAbort);
+    try {
+      if (groupTerminated !== null && !await groupTerminated) {
+        throw new ImsgCleanupUnverifiedError();
+      }
+    } finally {
+      if (forceKill !== null) clearTimeout(forceKill);
+    }
   }
 }
 

package/src/support-profile.ts

@@ -0,0 +1,7 @@
+/** Public product identity shared by the CLI, menu and static website. */
+export const ghostgetSupportProfile = Object.freeze({
+  id: "wrench",
+  name: "Ghostget",
+  valueProposition: "Support ongoing development of precise web tools for agents.",
+  updates: true,
+} as const);

package/src/support.ts

@@ -2,13 +2,7 @@ import {
   maybeShowSupportInvitation,
   runSupportCommand,
 } from "@hraness/support-foundation/node";
-
-const profile = {
-  id: "wrench",
-  name: "Ghostget",
-  valueProposition: "Support ongoing development of precise web tools for agents.",
-  updates: true,
-} as const;
+import { ghostgetSupportProfile as profile } from "./support-profile";
 
 type SupportOutput = {
   readonly stdout: (text: string) => unknown;
@@ -19,12 +13,12 @@ export async function runGhostgetSupportCommand(
   args: readonly string[],
   output: SupportOutput,
 ): Promise<number> {
-  const result = await runSupportCommand(profile, args);
+  const result = await runSupportCommand(profile, args, { command: ["ghostget"] });
   if (result.stdout !== "") output.stdout(result.stdout);
   if (result.stderr !== "") output.stderr(result.stderr);
   return result.exitCode;
 }
 
 export async function showGhostgetSupportInvitation(): Promise<void> {
-  await maybeShowSupportInvitation(profile, { usefulResult: true });
+  await maybeShowSupportInvitation(profile, { usefulResult: true, command: ["ghostget"] });
 }

package/src/usage.ts

@@ -8,8 +8,10 @@
 export const ghostgetUsage = `Usage:
   ghostget --version                                  Print the exact Ghostget release version
   ghostget support [--json]                           View optional product updates and support
-  ghostget support offer --json                       Check whether an agent invitation is due
-  ghostget support shown <id>                         Record an invitation presented to the user
+  ghostget support protocol --json                    Read the optional agent closeout protocol
+  ghostget support offer --json                       Claim an invitation when due at task closeout
+  ghostget support shown <id>                         Acknowledge human-facing output after presentation
+  ghostget support release <id>                       Cancel an invitation before presentation
   ghostget support dismiss|snooze|enable               Set shared invitation preferences
   ghostget support status --json                      Inspect local invitation preferences
   ghostget init [directory] [--json]                    Initialize a Markdown vault
@@ -192,4 +194,16 @@ Omni views:
   and Notification entities. 'omni read --cache-only' returns the merged local view
   without provider work. A normal omni read explicitly revalidates each declared
   source; --from-exact-cache rebuilds derivatives from exact snapshots only.
+
+Optional updates and support:
+  Successful standalone work may write a compact agent discovery notice to stderr,
+  including with --json or a PTY; command stdout and exit status stay unchanged.
+  Read support protocol --json, then check offer --json once at human task closeout.
+  Present persistently before shown <id>; acknowledgement records output, not consent.
+  Collapsed progress does not qualify. Final-only hosts omit shown; reservations expire
+  after ten minutes without a weekly cooldown, so a later task may offer again.
+  A quiet result needs no mention. No signup or payment occurs through these commands.
+  HRANESS_SUPPORT_AUDIENCE=agent|human|off selects presentation (default: agent).
+  Human presentation requires interactive stderr. Off suppresses due offers too.
+  HRANESS_SUPPORT=off disables ambient support; support dismiss opts out locally.
 `;

package/src/version.ts

@@ -1,2 +1,2 @@
 /** Canonical immutable Ghostget package release identity. */
-export const GHOSTGET_VERSION = "0.18.10" as const;
+export const GHOSTGET_VERSION = "0.18.13" as const;

package/src/whatsapp-client.ts

@@ -321,6 +321,8 @@ function preparedEnvironment(
   for (const [key, value] of Object.entries(process.env)) {
     if (typeof value === "string") environment[key] = value;
   }
+  // Package-owned SDK children never emit standalone support notices.
+  environment.GHOSTGET_CLI_DEPTH = "1";
   if (additions === undefined) return Object.freeze(environment);
   const source = record(additions, "options.environment");
   for (const [key, value] of Object.entries(source)) {
@@ -332,6 +334,7 @@ function preparedEnvironment(
       return fail("environment value is malformed");
     } else environment[key] = value;
   }
+  environment.GHOSTGET_CLI_DEPTH = "1";
   return Object.freeze(environment);
 }