@ossclip/core 0.1.26 → 0.1.28

package/src/producer/antigravity.ts

@@ -1,5 +1,6 @@
 import { z } from "zod/v4";
 import { run } from "../exec";
+import { attemptFactsLine } from "./failure";
 import type { LlmProvider } from "./provider";
 import { estimateTokens, type LlmUsage } from "./usage";
 // Shared fence-stripper for replies that wrap the JSON in prose/markdown.
@@ -24,6 +25,14 @@ export const AGY_PRINT_TIMEOUT = "10m";
  */
 export const MAX_AGY_PROMPT_BYTES = 700_000;
 
+/**
+ * agy's `--effort` levels. Exposed after the §143 hang incident (2026-08-22):
+ * untested at real scale whether a lower effort moves the hang, but the knob
+ * existed and we passed nothing — every call ran at agy's default with no way
+ * to try anything else.
+ */
+export type LlmEffort = "low" | "medium" | "high";
+
 /**
  * The argv for one `agy` print-mode call. Pure so the flag set is testable
  * without spawning anything. `--disable-slash-commands` because a transcript
@@ -31,7 +40,7 @@ export const MAX_AGY_PROMPT_BYTES = 700_000;
  */
 export function buildAgyArgs(
   prompt: string,
-  opts: { model?: string; schemaJson: string },
+  opts: { model?: string; effort?: LlmEffort; schemaJson: string },
 ): string[] {
   return [
     "-p",
@@ -44,6 +53,9 @@ export function buildAgyArgs(
     "--print-timeout",
     AGY_PRINT_TIMEOUT,
     ...(opts.model ? ["--model", opts.model] : []),
+    // Omitted entirely when unset — agy's own default stands, exactly as it
+    // did before the knob existed (§143).
+    ...(opts.effort ? ["--effort", opts.effort] : []),
   ];
 }
 
@@ -107,11 +119,159 @@ export function parseAgyEnvelope(stdout: string): {
  * Failures a retry cannot fix: missing auth and a bad model slug are
  * deterministic, and each retry burns another ~24k-token baseline call (agy's
  * own agent context) for nothing (FINDINGS §132, antigravity provider).
+ *
+ * The patterns were always right; the INPUT was wrong. Until 2026-08-22 this
+ * was handed `run()`'s rejection, and the contract §132 claimed for it — "the
+ * stderr tail is embedded, so auth/bad-slug are matchable here" — is false for
+ * real agy: a bad slug exits 1 with `invalid model selection …` in the STDOUT
+ * envelope and NOTHING on stderr (measured, 1.1.18). So the message this saw
+ * was our own echoed argv, which contains the slug but never the words
+ * "invalid model", and the documented fail-fast has never once fired in the
+ * field. It is now given `agyErrorText()` — the envelope's own error — which
+ * matches the shipped patterns as measured, with no pattern change at all.
+ *
+ * That is a real behaviour change (a bad slug now costs one call, not two),
+ * taken deliberately: it makes the code do what this comment has always said
+ * it does, rather than changing what it should do.
  */
 export function isNonRetryableAgyFailure(message: string): boolean {
   return /authentication|not logged in|login|unknown model|invalid model/i.test(message);
 }
 
+/**
+ * What actually went wrong, out of the two surfaces agy uses — measured
+ * against agy 1.1.18 on 2026-08-22, because none of it is documented:
+ *
+ *   print timeout fires  exit 1  stdout `{"status":"ERROR","error":"timeout
+ *                                waiting for response",…}`   stderr empty
+ *   unknown model slug   exit 1  stdout `{"status":"ERROR","error":"invalid
+ *                                model selection (--model …)…"}`  stderr empty
+ *   bad flag / usage     exit 2  stdout empty                 stderr usage text
+ *
+ * So the operational failures speak through the ENVELOPE and the process-level
+ * ones through stderr, and a reader of only one surface is blind to half of
+ * them. Preference order follows that: the envelope's own `error` first (it is
+ * agy's sentence about its own failure), then stderr for the exits that never
+ * reached the envelope, then the bare status, then whatever stdout held.
+ *
+ * Pure, and exported so the surfaces are testable without spawning agy. agy's
+ * wording is not a contract we control — only the two surfaces are — which is
+ * why callers classify loosely and print the raw text either way.
+ */
+export function agyErrorText(stdout: string, stderr: string): string {
+  const env = parseAgyEnvelope(stdout);
+  if (env.error?.trim()) return env.error.trim();
+  if (stderr.trim()) return stderr.trim().slice(-2000);
+  if (env.status) return `agy reported status ${env.status}`;
+  if (stdout.trim()) return `agy replied with no envelope: ${stdout.trim().slice(0, 300)}`;
+  return "agy printed nothing";
+}
+
+/** What the failure text says actually went wrong. See `classifyAgyFailure`. */
+export type AgyFailureClass = "auth" | "model" | "timeout" | "schema" | "unknown";
+
+/**
+ * Classify a failure so the error can say what happened instead of guessing.
+ * Pure and exported so every class is assertable without spawning agy. The
+ * input is `agyErrorText()` — agy's own sentence — not `run()`'s rejection.
+ *
+ * The incident (2026-08-22, FINDINGS §132): a `--produce --aspect 16:9` run on
+ * an 11-minute take timed out twice at AGY_PRINT_TIMEOUT — 10m each, 25
+ * minutes burned — and then died with "Is Antigravity installed and logged
+ * in?", while agy was installed, logged in and working. The hint was appended
+ * unconditionally, so every failure was reported as an auth failure and this
+ * one sent the user to debug auth after a 25-minute wait.
+ *
+ * Anchors, and how much each is worth:
+ *  - `timeout` and `model` are MEASURED (agy 1.1.18): "timeout waiting for
+ *    response" and "invalid model selection (--model …)". The looser
+ *    alternatives stay beside them because the exact strings are agy's to
+ *    change without telling us — and because an externally killed agy (a
+ *    signal, not agy's own clock) surfaces differently again.
+ *  - `auth` is INFERRED, not measured: establishing it would mean signing the
+ *    user out. Its patterns are exactly the ones `isNonRetryableAgyFailure`
+ *    has always used, so an auth failure can never classify worse than it did
+ *    before this change, and both measured samples put operational reasons in
+ *    the same envelope field, so there is no reason to expect auth elsewhere.
+ *  - `schema` matches what OUR OWN code leaves in `lastError` — `extractJson-
+ *    Object`'s message, JSON.parse's, and zod's issue array.
+ *
+ * A miss costs the headline and the class-gated advice, never the facts: the
+ * attempt line below prints for every class, and it is what actually
+ * self-diagnoses a hang.
+ */
+export function classifyAgyFailure(message: string): AgyFailureClass {
+  if (/authentication|not logged in|login/i.test(message)) return "auth";
+  if (/unknown model|invalid model/i.test(message)) return "model";
+  if (/timed? ?out|ETIMEDOUT|SIGTERM|SIGKILL/i.test(message)) return "timeout";
+  const schemaish = /no JSON object in reply|is not valid JSON|Unexpected (token|end of)|"code":\s*"/i;
+  if (schemaish.test(message)) return "schema";
+  return "unknown";
+}
+
+/**
+ * The error thrown when every attempt failed. Pure so the wording is testable
+ * without spawning agy, and built around one rule learned from the 2026-08-22
+ * incident: the ATTEMPT FACTS print for every class, because they self-diagnose
+ * regardless of what the classifier decided. "2 attempts, 10m0s and 10m0s,
+ * --print-timeout 10m" tells a user the call hung better than any guess we
+ * could make, and it stays true when the guess is wrong.
+ *
+ * Guidance, by contrast, is class-gated: the sign-in hint only for `auth`, and
+ * for `timeout` the actual escape hatch — another provider, or no planner at
+ * all — named the way the oversized-prompt error above names them.
+ */
+export function agyFailureMessage(parts: {
+  bin: string;
+  schemaName: string;
+  lastError: string;
+  /** Wall time of every attempt that ran, in order. */
+  attemptMs: readonly number[];
+  printTimeout: string;
+}): string {
+  const cls = classifyAgyFailure(parts.lastError);
+  const headline =
+    cls === "timeout"
+      ? " — the call timed out"
+      : cls === "schema"
+        ? " — the reply never matched the schema"
+        : "";
+  const detail = parts.lastError.trim().slice(0, 400) || "agy printed nothing";
+  const lines = [
+    `agy CLI ('${parts.bin}') did not produce valid ${parts.schemaName} JSON${headline}: ${detail}`,
+    attemptFactsLine(parts.attemptMs, `--print-timeout ${parts.printTimeout}`),
+  ];
+  if (cls === "auth") {
+    lines.push(
+      `Is Antigravity installed and logged in? (https://antigravity.google — run 'agy' once interactively to sign in)`,
+    );
+  }
+  if (cls === "timeout") {
+    lines.push(
+      `A long take can outrun agy's ${parts.printTimeout} print timeout. ` +
+        `Use --llm claude-cli (a logged-in Claude Code subscription) or --llm gemini (needs GEMINI_API_KEY), ` +
+        `or drop --produce to cut and caption without a planner.`,
+    );
+  }
+  return lines.join("\n");
+}
+
+/**
+ * The provider's terminal error, carrying the failure class as DATA. The
+ * message is written for humans and free to reword; a provider-fallback
+ * decorator that branches on what failed must read `failureClass`, never
+ * re-parse the prose.
+ */
+export class AgyError extends Error {
+  constructor(
+    message: string,
+    readonly failureClass: AgyFailureClass,
+  ) {
+    super(message);
+    this.name = "AgyError";
+  }
+}
+
 /**
  * Google Antigravity via the locally installed `agy` CLI. Uses whatever auth
  * the CLI holds — a logged-in subscription, so producing a video consumes
@@ -131,9 +291,12 @@ export class AntigravityProvider implements LlmProvider {
   readonly name = "antigravity";
   readonly usage: LlmUsage[] = [];
 
+  // A trailing options bag rather than a fourth positional: every existing
+  // `new AntigravityProvider(model, bin)` call site keeps compiling unchanged.
   constructor(
     private model?: string,
     private bin: string = process.env.OSSCLIP_AGY_BIN ?? "agy",
+    private opts: { effort?: LlmEffort } = {},
   ) {}
 
   async complete<T>(req: {
@@ -149,6 +312,11 @@ export class AntigravityProvider implements LlmProvider {
       `No markdown fences, no commentary, no tool use — just the JSON:\n${schemaText}`;
 
     let lastError = "";
+    // Wall time of every attempt that FAILED, in order — the facts the final
+    // error reports. Kept separately from `usage`, which only records attempts
+    // that got as far as an envelope: a call killed by --print-timeout never
+    // does, and a 10-minute hang is exactly the attempt a user needs to see.
+    const attemptMs: number[] = [];
     for (let attempt = 0; attempt < 2; attempt++) {
       const prompt =
         attempt === 0
@@ -164,41 +332,78 @@ export class AntigravityProvider implements LlmProvider {
       }
       const started = Date.now();
       let stdout = "";
+      let stderr = "";
       try {
-        ({ stdout } = await run(
+        // allowNonZero, and it is load-bearing: agy reports its operational
+        // failures as exit 1 with the reason in the STDOUT envelope and
+        // nothing on stderr (measured 1.1.18 — see `agyErrorText`). run()'s
+        // default reject path keeps only the stderr tail, so it threw away
+        // every one of those reasons and handed this loop our own echoed
+        // argv instead. Resolving non-zero exits and reading the envelope is
+        // what makes both the message AND the fail-fast work.
+        ({ stdout, stderr } = await run(
           this.bin,
-          buildAgyArgs(prompt, { model: this.model, schemaJson: schemaText }),
+          buildAgyArgs(prompt, {
+            model: this.model,
+            effort: this.opts.effort,
+            schemaJson: schemaText,
+          }),
+          { allowNonZero: true },
         ));
       } catch (err) {
+        // Only a spawn failure reaches here now: agy not on PATH, or not
+        // executable. Nothing was spent, and no retry can install it.
+        attemptMs.push(Date.now() - started);
         lastError = err instanceof Error ? err.message : String(err);
-        // run() embeds the stderr tail in its rejection, so auth/bad-slug
-        // failures are matchable here and fail fast instead of re-spending.
         if (isNonRetryableAgyFailure(lastError)) break;
+        // An externally killed spawn (SIGTERM/SIGKILL) classifies as timeout,
+        // and is as persistent as an expired --print-timeout — same fail-fast
+        // as the envelope path below.
+        if (classifyAgyFailure(lastError) === "timeout") break;
         continue;
       }
+      const elapsed = Date.now() - started;
       // Recorded per ATTEMPT, before validation: a reply that failed the
       // schema still spent the tokens, and a retry is exactly the cost a user
       // would want to see rather than have quietly absorbed.
       const envelope = parseAgyEnvelope(stdout);
-      this.usage.push({
-        provider: this.name,
-        // The envelope names no model, so record what was asked for — or the
-        // honest placeholder, which the cost report declines to price.
-        model: this.model ?? "antigravity-default",
-        schemaName: req.schemaName,
-        inputTokens: envelope.inputTokens ?? estimateTokens(prompt),
-        outputTokens: envelope.outputTokens ?? estimateTokens(envelope.response ?? stdout),
-        cachedInputTokens: envelope.cachedInputTokens,
-        exact: envelope.inputTokens !== undefined,
-        // The whole point of this provider: agy's cached sign-in means the
-        // subscription pays, not a card, and agy reports no cost to forward.
-        billed: false,
-        ms: Date.now() - started,
-      });
+      // Gated on stdout now that non-zero exits resolve: a call that printed
+      // NOTHING never reached the model (exit 2, a usage error) and must not
+      // be booked as an estimated ~24k-token call. Anything that did reply —
+      // including an ERROR envelope reporting zeros — is still recorded.
+      if (stdout.trim()) {
+        this.usage.push({
+          provider: this.name,
+          // The envelope names no model, so record what was asked for — or the
+          // honest placeholder, which the cost report declines to price.
+          model: this.model ?? "antigravity-default",
+          schemaName: req.schemaName,
+          inputTokens: envelope.inputTokens ?? estimateTokens(prompt),
+          outputTokens: envelope.outputTokens ?? estimateTokens(envelope.response ?? stdout),
+          cachedInputTokens: envelope.cachedInputTokens,
+          exact: envelope.inputTokens !== undefined,
+          // The whole point of this provider: agy's cached sign-in means the
+          // subscription pays, not a card, and agy reports no cost to forward.
+          billed: false,
+          ms: elapsed,
+          // The envelope's own verdict (§143): a failed attempt's cost stays
+          // visible, but attribution (the production.json stamp) skips it.
+          failed: envelope.status !== "SUCCESS" || undefined,
+        });
+      }
+      // SUCCESS is the envelope's own word for "this worked" (§132 lists the
+      // status enum), and with non-zero exits resolving it is now the ONLY
+      // success test — an exit code we no longer see cannot be one.
       if (envelope.status !== "SUCCESS") {
-        lastError =
-          envelope.error ?? `agy reported status ${envelope.status ?? "unknown"}: ${stdout.slice(0, 300)}`;
+        attemptMs.push(elapsed);
+        lastError = agyErrorText(stdout, stderr);
         if (isNonRetryableAgyFailure(lastError)) break;
+        // A timed-out call never succeeds on retry at this call size —
+        // measured 2026-08-22: a ~63k-token beat-sheet call expired at the
+        // 10m --print-timeout twice in a row, so the second attempt only
+        // doubled the wall clock to 20 minutes. Fail fast; the escape hatch
+        // is another provider, not the same call again.
+        if (classifyAgyFailure(lastError) === "timeout") break;
         continue;
       }
       try {
@@ -209,12 +414,19 @@ export class AntigravityProvider implements LlmProvider {
         }
         return req.schema.parse(JSON.parse(extractJsonObject(envelope.response ?? stdout)));
       } catch (err) {
+        attemptMs.push(elapsed);
         lastError = err instanceof Error ? err.message : String(err);
       }
     }
-    throw new Error(
-      `agy CLI ('${this.bin}') did not produce valid ${req.schemaName} JSON: ${lastError.slice(0, 400)}\n` +
-        `Is Antigravity installed and logged in? (https://antigravity.google — run 'agy' once interactively to sign in)`,
+    throw new AgyError(
+      agyFailureMessage({
+        bin: this.bin,
+        schemaName: req.schemaName,
+        lastError,
+        attemptMs,
+        printTimeout: AGY_PRINT_TIMEOUT,
+      }),
+      classifyAgyFailure(lastError),
     );
   }
 }

package/src/producer/beats.ts

@@ -99,7 +99,37 @@ export const ClipBeatSheetSchema = BeatSheetSchema.extend({
   ),
 });
 
-export const PRODUCER_SYSTEM = `You are the producer for a short-form vertical video (Reels/Shorts/TikTok). You receive a word-indexed transcript of a talking-head take that has already been cut. Your job is EDITORIAL: segment the take into moments, pick which moments deserve a graphic scene, and write the on-screen copy.
+/**
+ * Bump whenever `producerSystem`/`buildBeatsUserPrompt` change what they ask
+ * for: a prompt change changes the answer, so the beat-sheet/scenes cache key
+ * carries this (the §78 cache-key posture, same role as
+ * YOUTUBE_PROMPT_VERSION) — an old cached sheet must not survive a new prompt.
+ *
+ * v2: the system prompt stopped calling every output "vertical" (see
+ * `producerSystem`).
+ */
+export const PRODUCER_PROMPT_VERSION = "v2";
+
+/**
+ * The editorial system prompt, in the shape the output actually has.
+ *
+ * The opening sentence used to hardcode "short-form vertical video
+ * (Reels/Shorts/TikTok)" for every run, while `buildBeatsUserPrompt` has told
+ * 16:9 runs "Output frame: LANDSCAPE 16:9" since R21 §101 — so a landscape
+ * produce handed the model two contradictory descriptions of the same frame
+ * and left it to reconcile them (confirmed on a live 16:9 run, 2026-08).
+ *
+ * ONLY that sentence varies. Everything below it is the tuned 9:16 wording,
+ * byte-identical, and the portrait default must stay byte-identical to what
+ * shipped — the virality grammar was tuned against real runs of it, and a
+ * silent reword is a silent re-tune.
+ */
+export function producerSystem(aspect?: "9:16" | "16:9"): string {
+  const shape =
+    aspect === "16:9"
+      ? "a landscape video (YouTube)"
+      : "a short-form vertical video (Reels/Shorts/TikTok)";
+  return `You are the producer for ${shape}. You receive a word-indexed transcript of a talking-head take that has already been cut. Your job is EDITORIAL: segment the take into moments, pick which moments deserve a graphic scene, and write the on-screen copy.
 
 Virality grammar — follow these as hard policies:
 - The first moment is the hook: the strongest claim or number anywhere in the take, on screen within 2 seconds.
@@ -115,10 +145,19 @@ Virality grammar — follow these as hard policies:
 - The transcript is ASR output and may contain mishearings: an unfamiliar proper noun is more likely a mistranscription of a common phrase than a real entity — write on-screen copy with the common-sense reading, never a suspected mishearing.
 - FRAMING: when the prompt carries a "Camera framing" brief, it is measured from the footage and is a HARD constraint: on words marked CLOSE, never choose a layout listed as UNAVAILABLE there — pick a \`layout\` that keeps the whole head in frame (pip-bubble, graphic-only, full-bleed) or leave the moment as "none". You may set \`layout\` on any moment; omit it to accept the component's default.
 - COVER: also write \`coverText\` — the hook compressed to a thumbnail headline, AT MOST ${COVER_MAX_WORDS} WORDS. It is read at a glance in a profile grid, so it must stand alone without the video: the claim or the number, no lead-in, no ellipsis.`;
+}
+
+/**
+ * The portrait prompt, kept as a named export because it is part of
+ * @ossclip/core's public surface (`export * from "./producer/beats"`) and
+ * removing it would break an importer for nothing. Equal to
+ * `producerSystem()` by construction — never a second copy of the text.
+ */
+export const PRODUCER_SYSTEM = producerSystem();
 
 /**
  * The `--clip` request, appended to the USER prompt (R19 §93d). The tuned
- * PRODUCER_SYSTEM stays untouched — this adds the window request without
+ * system prompt stays untouched — this adds the window request without
  * rewriting the editorial instructions the beat sheet already follows.
  */
 export function buildClipAddendum(targetSec: number): string {
@@ -508,7 +547,9 @@ export async function generateBeatSheet(
     // Same editorial call, extended schema (R19 §93d) — the highlight and the
     // beat sheet come from ONE judgement, so they cannot disagree.
     const raw = await provider.complete({
-      system: PRODUCER_SYSTEM,
+      // Same aspect the user prompt was built with — the two halves of one
+      // call must describe the same frame.
+      system: producerSystem(aspect),
       user,
       schema: ClipBeatSheetSchema,
       schemaName: "clip_beat_sheet",
@@ -517,7 +558,7 @@ export async function generateBeatSheet(
     return { ...normalizeBeatSheet(raw, transcript, null), asked, highlight: raw.highlight };
   }
   const raw = await provider.complete({
-    system: PRODUCER_SYSTEM,
+    system: producerSystem(aspect),
     user,
     schema: BeatSheetSchema,
     schemaName: "beat_sheet",

package/src/producer/claude-cli.ts

@@ -1,5 +1,6 @@
 import { z } from "zod/v4";
 import { run } from "../exec";
+import { attemptFactsLine } from "./failure";
 import type { LlmProvider } from "./provider";
 import { estimateTokens, type LlmUsage } from "./usage";
 
@@ -38,6 +39,8 @@ export class ClaudeCliProvider implements LlmProvider {
       `No markdown fences, no commentary, no tool use — just the JSON:\n${schemaText}`;
 
     let lastError = "";
+    /** Wall time of every failed attempt — see `claudeCliFailureMessage`. */
+    const attemptMs: number[] = [];
     for (let attempt = 0; attempt < 2; attempt++) {
       const prompt =
         attempt === 0
@@ -50,6 +53,7 @@ export class ClaudeCliProvider implements LlmProvider {
       try {
         ({ stdout } = await run(this.bin, args, { stdin: prompt }));
       } catch (err) {
+        attemptMs.push(Date.now() - started);
         lastError = err instanceof Error ? err.message : String(err);
         continue;
       }
@@ -75,16 +79,92 @@ export class ClaudeCliProvider implements LlmProvider {
       try {
         return req.schema.parse(JSON.parse(extractJsonObject(unwrapCliEnvelope(stdout))));
       } catch (err) {
+        attemptMs.push(Date.now() - started);
         lastError = err instanceof Error ? err.message : String(err);
       }
     }
     throw new Error(
-      `claude CLI ('${this.bin}') did not produce valid ${req.schemaName} JSON: ${lastError.slice(0, 400)}\n` +
-        `Is Claude Code installed and logged in? (npm i -g @anthropic-ai/claude-code; run 'claude' once to /login)`,
+      claudeCliFailureMessage({ bin: this.bin, schemaName: req.schemaName, lastError, attemptMs }),
     );
   }
 }
 
+/** What the failure text says went wrong. See `classifyClaudeCliFailure`. */
+export type ClaudeCliFailureClass = "auth" | "model" | "timeout" | "schema" | "unknown";
+
+/**
+ * Classify a `claude -p` failure. Pure, and exported so each class is
+ * assertable without spawning the CLI.
+ *
+ * Same disease as agy's (FINDINGS §132): the sign-in hint below used to be
+ * appended to EVERY failure, so a bad model slug or a schema-repair loop told
+ * the user to check a login that was fine. Same cure — classify, print the
+ * attempt facts unconditionally, gate the advice.
+ *
+ * The surfaces are NOT the same, and this one was measured too (Claude Code,
+ * 2026-08-22, a bad `--model` slug): exit 1, a machine-readable
+ * `[claude-code:unrecognized_model] {…}` on STDERR, and a human sentence in
+ * the stdout envelope's `result`. Because it uses stderr — and because the
+ * prompt rides STDIN here, so `run()`'s rejection echoes a short argv rather
+ * than the whole transcript — the rejection message this receives already
+ * carries the reason, and no `allowNonZero` change is needed to see it.
+ *
+ * `auth` is inferred, not measured: establishing it would mean signing the
+ * user out. Its patterns are widened only to things that cannot mean anything
+ * else, so a real auth failure still gets the hint it always got.
+ */
+export function classifyClaudeCliFailure(message: string): ClaudeCliFailureClass {
+  if (/invalid api key|authentication|not logged in|\/login|unauthorized|oauth/i.test(message))
+    return "auth";
+  if (/unrecognized_model|unknown model|invalid model|model .* not (found|recognized)/i.test(message))
+    return "model";
+  if (/timed? ?out|ETIMEDOUT|SIGTERM|SIGKILL/i.test(message)) return "timeout";
+  const schemaish = /no JSON object in reply|is not valid JSON|Unexpected (token|end of)|"code":\s*"/i;
+  if (schemaish.test(message)) return "schema";
+  return "unknown";
+}
+
+/**
+ * The error thrown when both attempts failed. The attempt facts print for
+ * every class because they self-diagnose regardless of the classification
+ * (§132); the sign-in hint is gated to `auth`, and a model failure points at
+ * the flag that actually caused it.
+ */
+export function claudeCliFailureMessage(parts: {
+  bin: string;
+  schemaName: string;
+  lastError: string;
+  attemptMs: readonly number[];
+}): string {
+  const cls = classifyClaudeCliFailure(parts.lastError);
+  const headline =
+    cls === "timeout"
+      ? " — the call timed out"
+      : cls === "schema"
+        ? " — the reply never matched the schema"
+        : "";
+  const lines = [
+    `claude CLI ('${parts.bin}') did not produce valid ${parts.schemaName} JSON${headline}: ` +
+      (parts.lastError.trim().slice(0, 400) || "claude printed nothing"),
+    attemptFactsLine(parts.attemptMs),
+  ];
+  if (cls === "auth") {
+    lines.push(
+      `Is Claude Code installed and logged in? (npm i -g @anthropic-ai/claude-code; run 'claude' once to /login)`,
+    );
+  }
+  if (cls === "model") {
+    lines.push(`Check the --llm-model slug, or drop it to use the CLI's own default model.`);
+  }
+  if (cls === "timeout") {
+    lines.push(
+      `Use --llm antigravity (a logged-in Antigravity subscription) or --llm gemini (needs GEMINI_API_KEY), ` +
+        `or drop --produce to cut and caption without a planner.`,
+    );
+  }
+  return lines.join("\n");
+}
+
 /**
  * The accounting half of the same envelope: tokens, cost and model, all
  * optional because the CLI's envelope shape is not ours to depend on. Every

package/src/producer/failure.ts

@@ -0,0 +1,40 @@
+/**
+ * The facts every failed LLM call can state without guessing why it failed.
+ *
+ * From the 2026-08-22 incident (FINDINGS §132): a `--produce --aspect 16:9`
+ * run on an 11-minute take timed out twice at agy's print timeout — 10m each,
+ * 25 minutes burned — and died with "Is Antigravity installed and logged in?"
+ * on an agy that was installed, logged in and working. What that user needed
+ * was not a better guess, it was the shape of the wait: two attempts, ten
+ * minutes each. Attempt facts self-diagnose a hang, and they stay true when
+ * the classification is wrong — so both CLI providers print them for EVERY
+ * failure class, and gate only the advice.
+ *
+ * Pure, and shared so the two providers cannot drift into two formats for the
+ * same sentence.
+ */
+
+/** `600_000 → "10m0s"`, `1_500 → "1.5s"` — an at-a-glance wall time. */
+export function formatElapsed(ms: number): string {
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  // Floored, not rounded: 1m59.6s must not print as "1m60s".
+  return `${Math.floor(ms / 60_000)}m${Math.floor((ms % 60_000) / 1000)}s`;
+}
+
+/**
+ * "2 attempts, 10m0s and 10m0s" — how many calls ran and how long each took,
+ * with `extra` appended for a provider that has a clock worth naming (agy's
+ * `--print-timeout`). An empty list still says "0 attempts": a call that never
+ * spawned is itself the diagnosis.
+ */
+export function attemptFactsLine(attemptMs: readonly number[], extra?: string): string {
+  const times = attemptMs.map(formatElapsed);
+  const listed =
+    times.length > 1
+      ? `${times.slice(0, -1).join(", ")} and ${times[times.length - 1]}`
+      : (times[0] ?? "");
+  return (
+    `${attemptMs.length} attempt${attemptMs.length === 1 ? "" : "s"}` +
+    `${listed ? `, ${listed}` : ""}${extra ? `, ${extra}` : ""}.`
+  );
+}