@ossclip/core 0.1.27 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/core",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
   "type": "module",
   "license": "MIT",

package/src/browser.ts

@@ -45,11 +45,72 @@ export {
 // types only). The editor's load-path repair needs the MAP, not the raw span
 // array, to decide whether a repair is possible at all — see
 // `anchorCaptionLines` (§137): a non-empty array can still build an empty map.
-export { mapFromKeptSpans, TimeMap, type KeptSpan } from "./timemap";
+// `mapsClose` rides along since cut review step 4: the editor's playhead
+// hand-off across a live re-cut needs "did the clock actually change" to be
+// the SAME float-tolerant comparison `livePreviewMap`'s identity gate uses,
+// or a 1-ulp drift could seek the player for nothing.
+export { mapFromKeptSpans, mapsClose, TimeMap, type KeptSpan } from "./timemap";
 // The §35 cover word cap. The editor's CoverPanel shows the trimmed headline
 // live as you type, and restating the trimming rules there would drift from
 // the one the regenerate endpoint actually renders with. Imported from
 // ./cover-headline, NOT ./cover — that module is node all the way down
 // (node:fs, ./exec), which is exactly what this surface exists to keep out.
 export { COVER_MAX_WORDS, coverHeadline } from "./cover-headline";
-export type { Probe, Production, RenderSettings, Segment, Transcript, Word } from "./schema";
+// The cleanup veto layer (cut review step 3), VALUE exports and browser-safe:
+// cutlist.ts imports nothing but types from ./schema — verified before this
+// export, zero node built-ins in its graph. The editor marks vetoed seams
+// with the SAME `applyCleanupChoices` produce renders with (the
+// buildCoverRender one-implementation-two-callers pattern); a browser copy is
+// how the preview and the render would drift. `buildCutlist` itself rides
+// along in the module graph but stays unexported here on purpose — the
+// editor must never rebuild the proposal, only apply choices to the one
+// produce recorded.
+export {
+  applyCleanupChoices,
+  cleanupVetoable,
+  vetoedRemovals,
+  type CleanupChoices,
+} from "./cutlist";
+// The live post-veto preview (cut review step 4), VALUE exports and
+// browser-safe: retime-preview.ts composes cutlist + recut + timemap — all
+// already in this surface's runtime graph (recut.ts imports only overrides
+// and timemap, zero node built-ins, verified before this export). The editor
+// re-cuts its preview clock with the SAME `applyCleanupChoices` +
+// `subtractRangesFromCutlist` sequence produce runs and re-times every prop
+// through the SAME `remapPoint` produce re-anchors with — one implementation,
+// two callers, so the preview cannot drift from the render.
+// `previewClockMappers` rides along (step 4 follow-up): the surfaces that
+// speak in single instants — transcript seeks, ghost bands, the cover
+// panel's playhead — need the same walk as a point function, identity when
+// no re-cut is live, threaded by App so no consumer learns the machinery.
+// `cutRangeToOldClock` is the WRITE direction's range half (the follow-up's
+// follow-up): a cut gesture's live window converted to the old-clock frame
+// `doc.cuts` speaks, shared by the Inspector's button and App's delete
+// modal so the shrink/refuse verdict cannot drift between the two.
+export {
+  cutRangeToOldClock,
+  livePreviewMap,
+  previewClockMappers,
+  retimeForPreview,
+  type LivePreviewClocks,
+  type OldClockCutRange,
+  type PreviewClockMappers,
+  type RetimeablePreviewProps,
+  type RetimedPreviewFields,
+} from "./retime-preview";
+export type {
+  Probe,
+  Production,
+  // `RemovalReason` rides along with `Segment` (cut review step 2): the
+  // editor's reason→colour map is a `Record<RemovalReason, string>` precisely
+  // so a NEW reason in the vocabulary fails typecheck in the editor instead
+  // of silently drawing an uncoloured seam. (Since step 3 the schema module
+  // is in the runtime graph anyway — ./overrides imports RemovalReasonSchema
+  // for the `cleanup` key — but schema.ts is zod + scene-schema only, both
+  // already on this surface, so it stays browser-safe.)
+  RemovalReason,
+  RenderSettings,
+  Segment,
+  Transcript,
+  Word,
+} from "./schema";

package/src/config.ts

@@ -19,6 +19,16 @@ export interface OssclipConfig {
    * sheet always uses the main model. "same" disables tiering (FINDINGS §37).
    */
   fastModel?: string;
+  /**
+   * Reasoning effort for the antigravity provider — low | medium | high,
+   * agy's own `--effort` vocabulary. Consumed ONLY by antigravity today
+   * (§143: exposed after the hang incident — the knob existed and we passed
+   * nothing); every other provider ignores it. `--llm-effort` wins over this
+   * per run. File-only like `dictionary`; validated at the consumer
+   * (`resolveLlmEffort` in produce.ts), so a hand-edited `"max"` is one
+   * warning and an ignored key, never a coerced effort level.
+   */
+  llmEffort?: string;
   /**
    * Download URLs for models the ggerganov mirror doesn't host, keyed by the
    * bare model name — a user's own fine-tune needs one line:
@@ -196,6 +206,11 @@ export function loadConfig(): OssclipConfig {
     modelDir: process.env.OSSCLIP_MODEL_DIR ?? fileCfg.modelDir ?? DEFAULTS.modelDir,
     model: process.env.OSSCLIP_MODEL ?? fileCfg.model ?? DEFAULTS.model,
     fastModel: process.env.OSSCLIP_FAST_MODEL ?? fileCfg.fastModel,
+    // File-only, the `dictionary` posture — and deliberately NO env spelling
+    // (flag + config are the whole interface): validated where it is USED
+    // (`resolveLlmEffort` in produce.ts), so a hand-edited `"max"` earns one
+    // warning there and agy's default, never a coerced effort.
+    llmEffort: fileCfg.llmEffort,
     speaker: process.env.OSSCLIP_SPEAKER ?? fileCfg.speaker,
     openEditorAfterProduce: (process.env.OSSCLIP_OPEN_EDITOR ??
       fileCfg.openEditorAfterProduce) as OpenEditorPref | undefined,

package/src/cover-headline.ts

@@ -26,10 +26,17 @@
  */
 export const COVER_MAX_WORDS = 9;
 
-/** Trailing words that cannot end a headline — the truncation reads as broken. */
+/**
+ * Trailing words that cannot end a headline — the truncation reads as broken.
+ * Auxiliaries dangle exactly like prepositions: a real run (2026-08-22)
+ * truncated to "AI Gave Me Too Many Ideas. I Had" because the set had none.
+ * "i" is here for the same incident: popping "Had" alone leaves "…Ideas. I",
+ * a subject with its sentence cut off.
+ */
 const DANGLING = new Set([
   "a", "an", "and", "as", "at", "but", "by", "for", "from", "in", "is", "it",
   "of", "on", "or", "the", "to", "with", "that", "this", "my", "your", "so",
+  "had", "has", "have", "was", "were", "will", "can", "should", "i",
 ]);
 
 /**

package/src/cutlist.ts

@@ -329,3 +329,112 @@ export function buildCutlist({
 
   return segments;
 }
+
+/**
+ * The user's veto layer over the automatic cutlist (cut review step 3):
+ * `buildCutlist` PROPOSES removals, this is how the user DECLINES some of
+ * them — per category ("keep all pauses") and per individual span. Persisted
+ * as `overrides.json`'s `cleanup` key (`OverrideDocSchema.cleanup`, which
+ * owns the on-disk contract); this structural interface is what the pure
+ * functions below accept, so this module stays free of zod and of the
+ * overrides module — callable from produce AND from the editor bundle with
+ * nothing but the schema's own types.
+ */
+export interface CleanupChoices {
+  /**
+   * Category master switches. `false` = do not remove this reason's spans;
+   * absent (or a tolerated `true` on disk) = the default, remove as proposed.
+   */
+  reasons?: Partial<Record<RemovalReason, boolean>>;
+  /** Individual vetoes, SOURCE seconds — see `vetoedRemovals` for the
+   * overlap-based matching rule. */
+  kept?: readonly { srcIn: number; srcOut: number }[];
+}
+
+/**
+ * Whether a removal reason CAN be declined at all. `user` cuts come from the
+ * `cuts[]` array — declining your own cut is Restore on the cut, an existing
+ * gesture, and a second way to undo it would leave the entry behind as dead
+ * weight (there is no "not cut" state for a `cuts` entry to hold, per its
+ * schema comment). `clip` is the `--clip` window, a selection decision, not a
+ * cleanup — "keeping" a clip removal would silently un-clip the video. One
+ * predicate, exported, so produce, the panel's checkboxes and the timeline's
+ * seam handler cannot disagree about what is toggleable.
+ */
+export function cleanupVetoable(reason: RemovalReason | undefined): boolean {
+  return reason !== "user" && reason !== "clip";
+}
+
+/**
+ * The `remove` spans of `cutlist` that `choices` declines — the shared
+ * predicate under `applyCleanupChoices` (which re-keeps exactly these) and
+ * the editor's vetoed-seam state / produce's "kept N pause removal(s)" line
+ * (which both NAME them). One list, computed once, so what the seam shows as
+ * "will be kept" and what the render actually keeps cannot drift.
+ *
+ * Individual vetoes match by OVERLAP, deliberately NOT by float equality of
+ * endpoints: a re-produce can shift a removal's boundary by a frame (a
+ * changed silence threshold, a repair that re-stamps a word), and an
+ * exact-match veto that silently stops matching is the failure mode — the
+ * pause the user declined would quietly start being cut again. A partial
+ * overlap re-keeps the WHOLE removal span: a removal is one decision, not
+ * divisible.
+ */
+export function vetoedRemovals(
+  cutlist: readonly Segment[],
+  choices: CleanupChoices | undefined,
+): Segment[] {
+  if (!choices) return [];
+  const kept = choices.kept ?? [];
+  return cutlist.filter(
+    (seg) =>
+      seg.kind === "remove" &&
+      cleanupVetoable(seg.reason) &&
+      ((seg.reason !== undefined && choices.reasons?.[seg.reason] === false) ||
+        kept.some((k) => k.srcIn < seg.srcOut && k.srcOut > seg.srcIn)),
+  );
+}
+
+/**
+ * Apply the user's cleanup choices to the automatic cutlist: every vetoed
+ * removal (see `vetoedRemovals`) becomes a keep again, and adjacent keeps
+ * merge so the result stays the same canonical shape `buildCutlist` emits —
+ * a full partition of the input's range with no gaps, no overlaps, monotonic
+ * (the invariants `TimeMap`'s constructor checks). The partition holds BY
+ * CONSTRUCTION: spans are only relabelled and merged, never moved, so the
+ * covered range cannot change.
+ *
+ * `undefined`/empty choices return the input content unchanged — the
+ * regression anchor: an overrides.json with no `cleanup` key must produce a
+ * byte-identical render.
+ *
+ * ONE implementation, two callers (the `buildCoverRender` pattern): produce
+ * calls this between `buildCutlist` and the `TimeMap`; the editor calls it
+ * (via `@ossclip/core/browser`) to mark vetoed seams. A preview that
+ * disagrees with the render is worse than no preview.
+ */
+export function applyCleanupChoices(
+  cutlist: readonly Segment[],
+  choices: CleanupChoices | undefined,
+): Segment[] {
+  const vetoed = new Set(vetoedRemovals(cutlist, choices));
+  if (vetoed.size === 0) return [...cutlist];
+  const out: Segment[] = [];
+  for (const seg of cutlist) {
+    // A re-kept span drops `reason`/`confidence` — they described a removal
+    // that is no longer happening, and a keep carrying "pause" would read as
+    // a seventh segment kind everywhere the partition is consumed.
+    const next: Segment = vetoed.has(seg)
+      ? { srcIn: seg.srcIn, srcOut: seg.srcOut, kind: "keep" }
+      : seg;
+    const prev = out[out.length - 1];
+    if (prev !== undefined && prev.kind === "keep" && next.kind === "keep") {
+      // Merge in place — `prev` is always this function's own object (pushed
+      // below as a fresh literal when it is a keep), never the caller's.
+      prev.srcOut = next.srcOut;
+      continue;
+    }
+    out.push(next.kind === "keep" ? { srcIn: next.srcIn, srcOut: next.srcOut, kind: "keep" } : next);
+  }
+  return out;
+}

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./concat";
 export * from "./transcribe";
 export * from "./analyze";
 export * from "./cutlist";
+export * from "./retime-preview";
 export * from "./clip";
 export * from "./blooper";
 export * from "./retake";

package/src/overrides.ts

@@ -7,6 +7,7 @@ import {
   type SceneComponentId,
   type Theme,
 } from "./scene-schema";
+import { RemovalReasonSchema } from "./schema";
 import { resolveSceneProps } from "./scene-registry";
 import type { CaptionLine, CaptionWord } from "./captions";
 
@@ -435,6 +436,42 @@ export const OverrideDocSchema = z.object({
       }),
     )
     .default([]),
+  /**
+   * The user's VETO over the automatic cutlist (cut review step 3). `cuts`
+   * above is the user ADDING a removal; this is the user DECLINING one the
+   * pipeline proposed — opposite directions, deliberately not merged.
+   * Consumed by `applyCleanupChoices` (cutlist.ts, which owns the matching
+   * semantics), in produce and in the editor alike.
+   *
+   * `reasons` are the category master switches ("keep all pauses"). Only
+   * `false` is ever WRITTEN — a `true` entry restates the default, and the
+   * editor DELETES the key instead (the `hidden`/`captionsHidden` rule: an
+   * override with nothing to say). A `true` on disk is still parsed and
+   * means default, tolerantly. `user` and `clip` keys parse but are inert
+   * (`cleanupVetoable`): declining your own cut is Restore on the cut, and
+   * "keeping" the --clip window's removal would silently un-clip the video.
+   *
+   * `kept` are individual vetoes, in SOURCE seconds — and that anchoring is
+   * the whole trick, same as `cuts[].src` above: a bare output-seconds pair
+   * is meaningless once its own re-cut has happened, while source time is
+   * stable across every re-cut. This layer is therefore RECUT-IMMUNE BY
+   * CONSTRUCTION and — unlike `splits` and `scenes[*].timing` — needs NO
+   * entry in `remapOverridesThroughRecut`. Matching against the (possibly
+   * re-produced) cutlist is by OVERLAP, never float equality of endpoints;
+   * `vetoedRemovals` (cutlist.ts) states why.
+   *
+   * Optional-with-default like `splits`/`cuts`, so every overrides.json
+   * written before the key existed parses byte-identically; absent means
+   * today's behaviour exactly.
+   */
+  cleanup: z
+    .object({
+      reasons: z.partialRecord(RemovalReasonSchema, z.boolean()).default({}),
+      kept: z
+        .array(z.object({ srcIn: z.number().nonnegative(), srcOut: z.number().nonnegative() }))
+        .default([]),
+    })
+    .default({ reasons: {}, kept: [] }),
 });
 export type OverrideDoc = z.infer<typeof OverrideDocSchema>;
 

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),
     );
   }
 }