image-skill 0.1.35 → 0.1.37

package/CHANGELOG.md

@@ -4,6 +4,34 @@ This changelog tracks the public `image-skill` CLI package and public skill
 mirror. The npm package metadata remains the authority for tarball integrity and
 provenance; this file is the human- and agent-readable release map.
 
+## 0.1.37 - 2026-06-09
+
+- Fix (recovery): a live `create`/`edit` now leaves a recovery handle _before_
+  the blocking request. Every live (non-dry-run) call carries an idempotency
+  key even when you did not pass `--idempotency-key`, emits an `in_flight`
+  notice with that key to stderr, and writes a durable breadcrumb at
+  `<config-dir>/in-flight/<key>.json`. If the command is interrupted (for
+  example you kill a create that hangs on a long provider wait after the credit
+  was already reserved), re-run it with the surfaced key: the hosted API
+  replays the original job (returning the asset you already paid for) or
+  releases the reserved credit — never a double charge. The stdout JSON
+  envelope is unchanged. Fixes the "create debited credits but no live job or
+  asset surfaced" report (#1789).
+- Fix (recovery): the proxy-killed non-JSON 5xx retry recovery now echoes the
+  same idempotency key the charged request used, so the advertised retry
+  genuinely dedupes instead of minting a non-matching key (#1228 follow-up).
+
+## 0.1.36 - 2026-06-04
+
+- Fix (guide): `create --guide --json` now marks templated follow-up commands
+  explicitly with `data.next_command_copy_runnable`,
+  `data.next_command_missing_inputs`, and
+  `data.next_command_effect.requires_placeholder_substitution`. Auth signup,
+  prompt recovery, payment handoff, and input-asset templates remain visible to
+  agents, but placeholder values such as `AGENT_OR_OPERATOR_INBOX`,
+  `AGENT_NAME`, `RUNTIME_NAME`, `QUOTE_ID`, and `PAYMENT_ATTEMPT_ID` are no
+  longer presented as if the command can be copied blindly.
+
 ## 0.1.35 - 2026-06-04
 
 - Fix (CLI aliases): natural modality-first commands now route into the

package/bin/image-skill.mjs

@@ -7,7 +7,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.35";
+const VERSION = "0.1.37";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -65,6 +65,70 @@ const PAYMENT_CREDENTIAL_FLAGS = new Set([
   "provider-key",
   "provider-receipt",
 ]);
+const GUIDE_NEXT_COMMAND_PLACEHOLDERS = [
+  {
+    placeholder: "AGENT_OR_OPERATOR_INBOX",
+    flag: "--agent-contact",
+    value_description:
+      "Email-shaped durable contact inbox for the restricted agent identity; use an agent-owned inbox when available, otherwise an operator, team, or sponsor inbox.",
+    effect_description: "email-shaped durable contact inbox",
+    example: "agent-inbox@example.com",
+  },
+  {
+    placeholder: "AGENT_NAME",
+    flag: "--agent-name",
+    value_description:
+      "Stable display name for this restricted agent identity.",
+    effect_description: "stable agent identity name",
+    example: "codex-image-worker",
+  },
+  {
+    placeholder: "RUNTIME_NAME",
+    flag: "--runtime",
+    value_description:
+      "Stable name for the agent runtime or substrate using Image Skill.",
+    effect_description: "agent/runtime substrate name",
+    example: "codex-cli",
+  },
+  {
+    placeholder: "PROMPT",
+    flag: "--prompt",
+    value_description: "The real creative prompt to plan or create.",
+    effect_description: "real creative prompt",
+    example: "a compact field camera on a stainless workbench",
+  },
+  {
+    placeholder: "KEY",
+    flag: "--idempotency-key",
+    value_description:
+      "Unique idempotency key for this payment or create attempt.",
+    effect_description: "unique idempotency key",
+    example: "agent-generated-idempotency-key",
+  },
+  {
+    placeholder: "QUOTE_ID",
+    flag: "--quote-id",
+    value_description: "Quote id returned by the preceding credits quote call.",
+    effect_description: "quote id from credits quote",
+    example: null,
+  },
+  {
+    placeholder: "PAYMENT_ATTEMPT_ID",
+    flag: "--payment-attempt-id",
+    value_description:
+      "Payment attempt id returned by the preceding credits buy call.",
+    effect_description: "payment attempt id from credits buy",
+    example: null,
+  },
+  {
+    placeholder: "image_...",
+    flag: "--input",
+    value_description:
+      "Image Skill input asset id, usually from upload, assets, jobs, or a previous create.",
+    effect_description: "Image Skill input asset id",
+    example: null,
+  },
+];
 
 const argv = normalizePublicArgv(process.argv.slice(2));
 const result = await main(argv);
@@ -212,24 +276,26 @@ function helpKey(path) {
 function commandHelpByKey(key) {
   return {
     "": {
-      command: "image-skill help",
+      command: "help",
       usage:
-        "image-skill <doctor|trust|signup|auth|whoami|usage|quota|credits|models|capabilities|create|upload|edit|assets|jobs|activity|feedback> --json",
+        "image-skill <doctor|trust|signup|whoami|usage|quota|credits|capabilities|models|create|upload|edit|assets|jobs|activity|feedback> --json",
       docs_url: "https://image-skill.com/cli.md",
       commands: [
         "doctor",
         "trust",
         "signup --agent --agent-contact --agent-name NAME --runtime RUNTIME",
-        "auth status",
-        "auth save",
-        "auth logout",
         "whoami",
         "usage quota",
+        "quota",
         "credits methods",
-        "credits packs list",
         "credits quote",
+        "credits packs list",
         "credits buy",
         "credits status",
+        "capabilities",
+        "capabilities list",
+        "capabilities show",
+        "models",
         "models list",
         "models show",
         "create --guide",
@@ -237,8 +303,7 @@ function commandHelpByKey(key) {
         "video create --guide",
         "audio create --guide",
         "3d create --guide",
-        "capabilities list",
-        "capabilities show",
+        "create --dry-run",
         "create",
         "image edit",
         "upload",
@@ -329,7 +394,7 @@ function commandHelpByKey(key) {
     },
     "credits methods": {
       command: "image-skill credits methods help",
-      usage: "image-skill credits methods --json",
+      usage: "image-skill credits methods",
       docs_url: "https://image-skill.com/cli.md#image-skill-credits",
     },
     "credits packs": {
@@ -372,6 +437,16 @@ function commandHelpByKey(key) {
       usage:
         "image-skill models list --available --operation image.generate --json",
       docs_url: "https://image-skill.com/cli.md#image-skill-models",
+      optional_flags: [
+        "--available",
+        "--executable",
+        "--catalog-only",
+        "--operation",
+        "--modality",
+        "--provider",
+        "--summary",
+        "--details",
+      ],
     },
     "models show": {
       command: "image-skill models show help",
@@ -405,6 +480,9 @@ function commandHelpByKey(key) {
         "--model",
         "--aspect-ratio",
         "--output-count",
+        "--element-frontal",
+        "--element-reference",
+        "--reference-image",
         "--model-parameters-json",
         "--idempotency-key",
       ],
@@ -425,6 +503,8 @@ function commandHelpByKey(key) {
         "--model",
         "--mask",
         "--element-reference",
+        "--element-frontal",
+        "--reference-image",
         "--model-parameters-json",
         "--idempotency-key",
       ],
@@ -937,12 +1017,6 @@ async function credits(argv) {
       (flag) =>
         !["json", "api-base-url", "token", "token-stdin"].includes(flag),
     );
-    if (!flagBool(args, "json")) {
-      return invalid(
-        "image-skill credits methods",
-        "credits methods requires --json",
-      );
-    }
     if (args.positionals.length > 0 || unknownFlags.length > 0) {
       return invalid(
         "image-skill credits methods",
@@ -1033,7 +1107,7 @@ async function credits(argv) {
     if (paymentMethod === null) {
       return invalid(
         "image-skill credits quote",
-        "credits quote requires --payment-method from credits methods --json; use stripe_x402.exact.usdc for an agent-settleable browserless rail or stripe_checkout for a human Checkout handoff",
+        "credits quote requires --payment-method from credits methods; use stripe_x402.exact.usdc for an agent-settleable browserless rail or stripe_checkout for a human Checkout handoff",
       );
     }
     if (!PUBLIC_QUOTE_PAYMENT_METHODS.includes(paymentMethod)) {
@@ -1174,13 +1248,13 @@ async function models(argv) {
     subcommand === "list" || subcommand === "show" ? rest : argv,
   );
   if (subcommand === "show") {
-    const modelId = args.positionals[0];
-    if (modelId === undefined) {
+    if (args.positionals.length !== 1) {
       return invalid(
         "image-skill models show",
-        "models show requires MODEL_ID",
+        "models show requires exactly one MODEL_ID",
       );
     }
+    const modelId = args.positionals[0];
     return apiRequest({
       command: "image-skill models show",
       method: "GET",
@@ -1209,13 +1283,21 @@ async function models(argv) {
     apiBaseUrl: apiBase(args),
     path: query.path,
   });
-  return flagBool(args, "summary") ? withModelSummary(result) : result;
+  return flagBool(args, "details") ? result : withModelSummary(result);
 }
 
 function modelListQuery(args) {
   const available = flagBool(args, "available");
   const executable = flagBool(args, "executable");
   const catalogOnly = flagBool(args, "catalog-only");
+  const summary = flagBool(args, "summary");
+  const details = flagBool(args, "details");
+  if (summary && details) {
+    return {
+      ok: false,
+      message: "models list --summary cannot be combined with --details",
+    };
+  }
   if (catalogOnly && (available || executable)) {
     return {
       ok: false,
@@ -1233,6 +1315,9 @@ function modelListQuery(args) {
   if (catalogOnly) {
     params.set("catalog_only", "true");
   }
+  if (details) {
+    params.set("details", "true");
+  }
   addQueryValue(params, "operation", flagString(args, "operation"));
   addQueryValue(params, "modality", flagString(args, "modality"));
   addQueryValue(params, "provider", flagString(args, "provider"));
@@ -1248,6 +1333,9 @@ function withModelSummary(result) {
   if (!isRecord(data) || !Array.isArray(data.models)) {
     return result;
   }
+  if (data.summary?.result_shape === "compact_model_summary") {
+    return result;
+  }
   return {
     ...result,
     envelope: {
@@ -1257,7 +1345,7 @@ function withModelSummary(result) {
         summary: {
           ...(isRecord(data.summary) ? data.summary : {}),
           result_shape: "compact_model_summary",
-          full_list_command: "image-skill models list --json",
+          full_list_command: "image-skill models list --details --json",
         },
         models: data.models.map(modelSummaryRow),
       },
@@ -1268,11 +1356,13 @@ function withModelSummary(result) {
 function modelSummaryRow(model) {
   return {
     id: model.id,
+    default: model.default === true,
     display_name: model.display_name,
     provider_id: model.provider_id,
     mode: model.mode,
     status: model.status,
     availability_reason: model.availability_reason ?? null,
+    modality: model.modality ?? "image",
     supports: Array.isArray(model.supports) ? [...model.supports] : [],
     operations: Array.isArray(model.operations) ? [...model.operations] : [],
     task_tags: modelSummaryTaskTags(model),
@@ -1545,6 +1635,9 @@ async function createGuide(args) {
     commandPrefix: guideCommandPrefix,
     authConfigWritable: authConfigWrite?.ok ?? true,
   });
+  const nextCommandMissingInputs =
+    createGuideNextCommandMissingInputs(nextCommand);
+  const nextCommandCopyRunnable = nextCommandMissingInputs.length === 0;
   const escapeHatches = createGuideEscapeHatches({
     prompt: trimmedPrompt,
     selected,
@@ -1561,6 +1654,8 @@ async function createGuide(args) {
   const nextCommandEffect = createGuideNextCommandEffect(stage, {
     estimatedCredits,
     estimatedDebitUsdPerImage,
+    nextCommandCopyRunnable,
+    nextCommandMissingInputs,
   });
   const noSpendNextCommand =
     stage === "ready_to_create" ? escapeHatches.dry_run : null;
@@ -1580,6 +1675,7 @@ async function createGuide(args) {
   const guideWarning = createGuideWarning(stage, {
     nextCommandEffect,
     paymentSummary,
+    nextCommandCopyRunnable,
   });
   const selfFundNextCommand = stage === "quota_required" ? nextCommand : null;
   const selfFundNextCommandLabel = createGuideSelfFundNextCommandLabel(
@@ -1610,6 +1706,7 @@ async function createGuide(args) {
     authenticated,
     tokenSource: publicTokenSource,
     savedConfigPath: configPath(),
+    nextCommandCopyRunnable,
   });
   const selfFundHandoff = createGuideSelfFundHandoff(stage, {
     paymentSummary,
@@ -1703,6 +1800,8 @@ async function createGuide(args) {
     guide_warning: guideWarning,
     auth_ready: authReady,
     next_command: nextCommand,
+    next_command_copy_runnable: nextCommandCopyRunnable,
+    next_command_missing_inputs: nextCommandMissingInputs,
     next_command_effect: nextCommandEffect,
     no_spend_next_command: noSpendNextCommand,
     no_spend_next_command_label: noSpendNextCommandLabel,
@@ -2302,7 +2401,9 @@ function createGuideAuthReady(stage, input) {
     warning: ready
       ? "Current hosted auth is ready; data.next_command can reuse this auth context without exposing a raw token."
       : stage === "auth_required"
-        ? "Auth is not ready yet; run data.next_command to create a restricted agent identity, then rerun the guide."
+        ? input.nextCommandCopyRunnable
+          ? "Auth is not ready yet; run data.next_command to create a restricted agent identity, then rerun the guide."
+          : "Auth is not ready yet; fill data.next_command_missing_inputs before running the data.next_command signup template, then rerun the guide."
         : null,
   };
 }
@@ -2433,6 +2534,9 @@ function createGuideWalletSettlementHandoff({
 }
 
 function createGuideNextCommandEffect(stage, input) {
+  const placeholders = createGuideEffectPlaceholders(
+    input.nextCommandMissingInputs,
+  );
   const base = {
     label: "read_only_or_no_media_setup",
     no_spend: true,
@@ -2444,6 +2548,9 @@ function createGuideNextCommandEffect(stage, input) {
     media_write: false,
     estimated_credits: null,
     estimated_debit_usd_per_image: null,
+    copy_runnable: input.nextCommandCopyRunnable,
+    requires_placeholder_substitution: placeholders.length > 0,
+    placeholders,
     warning: null,
   };
   if (stage === "auth_required") {
@@ -2477,6 +2584,9 @@ function createGuideNextCommandEffect(stage, input) {
       media_write: true,
       estimated_credits: input.estimatedCredits,
       estimated_debit_usd_per_image: input.estimatedDebitUsdPerImage,
+      copy_runnable: input.nextCommandCopyRunnable,
+      requires_placeholder_substitution: placeholders.length > 0,
+      placeholders,
       warning:
         "data.next_command creates hosted media and can debit credits. For no-spend verification, run data.recommended_no_spend_command (same value as data.no_spend_next_command) instead.",
     };
@@ -2572,8 +2682,9 @@ function createGuideWarning(stage, input) {
       ...base,
       next_command_safety: "rerun_guide_no_spend",
       recommended_command_field: "next_command",
-      warning:
-        "data.next_command reruns the free guide with a real prompt; it does not call a provider, open payment, debit credits, or create media.",
+      warning: input.nextCommandCopyRunnable
+        ? "data.next_command reruns the free guide with a real prompt; it does not call a provider, open payment, debit credits, or create media."
+        : "data.next_command is a no-spend guide template; fill data.next_command_missing_inputs before running it. It does not call a provider, open payment, debit credits, or create media.",
     };
   }
   if (stage === "no_executable_model" || stage === "service_unreachable") {
@@ -2590,8 +2701,9 @@ function createGuideWarning(stage, input) {
       ...base,
       next_command_safety: "hosted_signup_no_spend_setup",
       recommended_command_field: "next_command",
-      warning:
-        "data.next_command is no-spend hosted signup/setup; it creates a restricted agent identity but does not call a provider, open payment, debit credits, or create media.",
+      warning: input.nextCommandCopyRunnable
+        ? "data.next_command is no-spend hosted signup/setup; it creates a restricted agent identity but does not call a provider, open payment, debit credits, or create media."
+        : "data.next_command is a no-spend hosted signup/setup template; fill data.next_command_missing_inputs before running it. It creates a restricted agent identity but does not call a provider, open payment, debit credits, or create media.",
     };
   }
   if (stage === "quota_required") {
@@ -2605,12 +2717,17 @@ function createGuideWarning(stage, input) {
       spend_required: true,
       recommended_command_field: "escape_hatches",
       payment_top_up_path: paymentTopUpPath,
-      warning:
-        paymentTopUpPath === "browserless_agent_self_fund"
+      warning: input.nextCommandCopyRunnable
+        ? paymentTopUpPath === "browserless_agent_self_fund"
           ? "data.next_command starts the browserless live-money top-up path; stay within the delegated cap, or use data.escape_hatches.payment_methods for read-only payment inspection."
           : paymentTopUpPath === "human_payment_handoff"
             ? "data.next_command starts a live-money payment handoff that needs human or browser completion; stay within the delegated cap, or use data.escape_hatches.payment_methods for read-only inspection."
-            : "data.next_command starts payment or quota recovery; inspect data.checks.payments before attempting live money, or use data.escape_hatches.payment_methods for read-only inspection.",
+            : "data.next_command starts payment or quota recovery; inspect data.checks.payments before attempting live money, or use data.escape_hatches.payment_methods for read-only inspection."
+        : paymentTopUpPath === "browserless_agent_self_fund"
+          ? "data.next_command is a browserless live-money top-up template; fill data.next_command_missing_inputs before running it, stay within the delegated cap, or use data.escape_hatches.payment_methods for read-only payment inspection."
+          : paymentTopUpPath === "human_payment_handoff"
+            ? "data.next_command is a live-money payment handoff template; fill data.next_command_missing_inputs before running it, stay within the delegated cap, or use data.escape_hatches.payment_methods for read-only inspection."
+            : "data.next_command is a live-money payment template; fill data.next_command_missing_inputs before running it, stay within the delegated cap, or use data.escape_hatches.payment_methods for read-only inspection.",
     };
   }
   return {
@@ -2624,6 +2741,40 @@ function createGuideWarning(stage, input) {
   };
 }
 
+function createGuideNextCommandMissingInputs(command) {
+  return GUIDE_NEXT_COMMAND_PLACEHOLDERS.filter((placeholder) =>
+    commandContainsTemplateToken(command, placeholder.placeholder),
+  ).map((placeholder) => ({
+    flag: placeholder.flag,
+    placeholder: placeholder.placeholder,
+    value_description: placeholder.value_description,
+    example: placeholder.example,
+  }));
+}
+
+function createGuideEffectPlaceholders(missingInputs) {
+  return missingInputs.map((input) => {
+    const placeholder = GUIDE_NEXT_COMMAND_PLACEHOLDERS.find(
+      (candidate) => candidate.placeholder === input.placeholder,
+    );
+    return {
+      token: input.placeholder,
+      description: placeholder?.effect_description ?? input.value_description,
+      required: true,
+    };
+  });
+}
+
+function commandContainsTemplateToken(command, token) {
+  return new RegExp(
+    `(^|[^A-Za-z0-9_])${escapeRegExp(token)}(?=$|[^A-Za-z0-9_])`,
+  ).test(command);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function createGuideNextCommand(stage, input) {
   if (stage === "prompt_required") {
     return renderGuideCommand("PROMPT", input.apiBaseUrl, input.commandPrefix, {
@@ -2975,7 +3126,21 @@ async function create(argv) {
   if (!references.ok) {
     return references.result;
   }
-  return apiRequest({
+  // A live (non-dry-run, authenticated) create is the only branch that spends
+  // credits. Give it a recovery handle BEFORE the blocking request (#1789).
+  const isLiveSpend = !flagBool(args, "dry-run") && token.token !== null;
+  const idempotencyKey = isLiveSpend
+    ? liveSpendIdempotencyKey(args, "create")
+    : flagString(args, "idempotency-key");
+  const inFlight = isLiveSpend
+    ? await recordInFlightSpend({
+        command: "image-skill create",
+        operation: "create",
+        idempotencyKey,
+        argv,
+      })
+    : null;
+  const result = await apiRequest({
     command: "image-skill create",
     method: "POST",
     apiBaseUrl: apiBase(args),
@@ -3010,15 +3175,15 @@ async function create(argv) {
       ...(modelParameters.value === null
         ? {}
         : { model_parameters: modelParameters.value }),
-      // Retry-safe dedupe (#1228): when provided, a retry with the same key does
-      // not double-charge after a transient 502 that already debited a credit.
-      ...(flagString(args, "idempotency-key") === null
-        ? {}
-        : { idempotency_key: flagString(args, "idempotency-key") }),
+      // Retry-safe dedupe (#1228/#1789): a live create always carries a key so a
+      // retry (or an interrupted-then-recovered run) dedupes to one charge.
+      ...(idempotencyKey === null ? {} : { idempotency_key: idempotencyKey }),
       dry_run: flagBool(args, "dry-run"),
       accept_unknown_cost: flagBool(args, "accept-unknown-cost"),
     },
   });
+  await clearInFlightSpend(inFlight);
+  return result;
 }
 
 async function upload(argv) {
@@ -3089,7 +3254,21 @@ async function edit(argv) {
   if (!modelParameters.ok) {
     return modelParameters.result;
   }
-  return apiRequest({
+  // A live (non-dry-run) edit spends credits; give it a recovery handle BEFORE
+  // the blocking request (#1789). Edit always carries a token.
+  const isLiveSpend = !flagBool(args, "dry-run");
+  const idempotencyKey = isLiveSpend
+    ? liveSpendIdempotencyKey(args, "edit")
+    : flagString(args, "idempotency-key");
+  const inFlight = isLiveSpend
+    ? await recordInFlightSpend({
+        command: "image-skill edit",
+        operation: "edit",
+        idempotencyKey,
+        argv,
+      })
+    : null;
+  const result = await apiRequest({
     command: "image-skill edit",
     method: "POST",
     apiBaseUrl: apiBase(args),
@@ -3122,14 +3301,14 @@ async function edit(argv) {
         ? {}
         : { model_parameters: modelParameters.value }),
       ...(flagBool(args, "dry-run") ? { dry_run: true } : {}),
-      // Retry-safe dedupe (#1228): see create — same key dedupes a retry that
-      // follows a transient 502 which already debited a credit.
-      ...(flagString(args, "idempotency-key") === null
-        ? {}
-        : { idempotency_key: flagString(args, "idempotency-key") }),
+      // Retry-safe dedupe (#1228/#1789): a live edit always carries a key so a
+      // retry (or an interrupted-then-recovered run) dedupes to one charge.
+      ...(idempotencyKey === null ? {} : { idempotency_key: idempotencyKey }),
       accept_unknown_cost: flagBool(args, "accept-unknown-cost"),
     },
   });
+  await clearInFlightSpend(inFlight);
+  return result;
 }
 
 async function assets(argv) {
@@ -4206,6 +4385,102 @@ async function fetchPublicText(url, options = {}) {
   }
 }
 
+// --- In-flight live-spend recovery breadcrumb (#1789) -----------------------
+// A live create/edit is one synchronous request that can block for the full
+// provider duration (often minutes). If the agent kills the process during that
+// wait, the hosted API may have already reserved a credit, yet the agent is left
+// with no job id, no trace, and no recovery handle — an orphaned debit it cannot
+// see or reconcile (the reservation only auto-releases on a 15-minute TTL).
+//
+// We close that loop on the client, BEFORE the blocking request: every live
+// spend carries an idempotency key, and we hand the agent that key (stderr) plus
+// a durable local breadcrumb. On interruption the agent re-runs the same command
+// with the same key; the hosted API replays the original job (returning the
+// asset already paid for) or releases the reserved credit — never a double
+// charge. See https://image-skill.com/cli.md#image-skill-create.
+
+function liveSpendIdempotencyKey(args, operation) {
+  const explicit = flagString(args, "idempotency-key");
+  if (explicit !== null) {
+    return explicit;
+  }
+  return `${operation}-${Date.now()}-${randomBytes(6).toString("hex")}`;
+}
+
+function inFlightSpendDir() {
+  return join(dirname(configPath()), "in-flight");
+}
+
+function recoverCommandFor(operation, idempotencyKey) {
+  return `image-skill ${operation} --idempotency-key ${idempotencyKey} <same arguments> --json`;
+}
+
+async function recordInFlightSpend(input) {
+  const { command, operation, idempotencyKey, argv } = input;
+  const recoverCommand = recoverCommandFor(operation, idempotencyKey);
+  const note =
+    "live spend may already be reserved. If this command is interrupted before it returns a result, re-run it with the idempotency_key above; the hosted API replays the original job or releases the reserved credit and never double-charges.";
+  // Persist the durable breadcrumb FIRST, then announce — so by the time the
+  // agent sees the stderr handle, the on-disk copy already exists (an operator
+  // or a later session can find an orphaned spend even when the transcript is
+  // gone).
+  const dir = inFlightSpendDir();
+  const path = join(dir, `${idempotencyKey}.json`);
+  let recordedPath = null;
+  try {
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      path,
+      `${JSON.stringify(
+        {
+          schema: "image-skill.in-flight-spend.v1",
+          command,
+          operation,
+          idempotency_key: idempotencyKey,
+          recover_command: recoverCommand,
+          argv,
+          started_at: new Date().toISOString(),
+        },
+        null,
+        2,
+      )}\n`,
+      { mode: 0o600 },
+    );
+    recordedPath = path;
+  } catch {
+    // The stderr notice below is the primary handle; a filesystem failure must
+    // not block the create/edit.
+  }
+  // stderr only — the stdout JSON envelope contract is unchanged. Even a killed
+  // process leaves this line in the agent's captured transcript.
+  try {
+    process.stderr.write(
+      `${JSON.stringify({
+        in_flight: {
+          command,
+          idempotency_key: idempotencyKey,
+          recover_command: recoverCommand,
+          note,
+        },
+      })}\n`,
+    );
+  } catch {
+    // diagnostics are best-effort; never block the spend on a write failure.
+  }
+  return recordedPath;
+}
+
+async function clearInFlightSpend(path) {
+  if (path === null || path === undefined) {
+    return;
+  }
+  try {
+    await rm(path, { force: true });
+  } catch {
+    // best-effort cleanup; a leftover breadcrumb is harmless.
+  }
+}
+
 async function apiRequest(input) {
   const url = new URL(input.path, ensureTrailingSlash(input.apiBaseUrl));
   try {