image-skill 0.1.42 → 0.1.44

package/bin/image-skill.mjs

@@ -1,18 +1,28 @@
 #!/usr/bin/env node
 import { createHash, randomBytes } from "node:crypto";
 import { createWriteStream } from "node:fs";
-import { chmod, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import {
+  chmod,
+  mkdir,
+  readdir,
+  readFile,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.42";
+const VERSION = "0.1.44";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
 const DEFAULT_NPM_REGISTRY_BASE_URL = "https://registry.npmjs.org";
 const PUBLIC_REPO_URL = "https://github.com/danielgwilson/image-skill-cli";
+const IN_FLIGHT_RESERVATION_TTL_MS = 15 * 60 * 1000;
+const IN_FLIGHT_SWEEP_AFTER_MS = 24 * 60 * 60 * 1000;
 const PROMPTLESS_EDIT_MODEL_IDS = new Set([
   "fal.flux-dev-redux",
   "fal.flux-krea-redux",
@@ -39,6 +49,9 @@ const HOSTED_SIGNUP_TOKEN_RETURNED_WARNING =
 const PUBLIC_NPX_COMMAND_PREFIX =
   "npm_config_update_notifier=false npx -y image-skill@latest";
 const CREDIT_UNIT_USD = 0.01;
+const TARGET_GROSS_MARGIN = 0.4;
+const PAYMENT_BACKED_CREDIT_PAYMENT_FEE_RATE = 0.015;
+const PAYMENT_BACKED_CREDIT_PAYMENT_FEE_MODEL = "stripe_stablecoin_usd_percent";
 const MODALITY_COMMAND_ALIASES = new Map([
   ["image", { command: "create", intent: null }],
   ["video", { command: "create", intent: "video" }],
@@ -327,7 +340,8 @@ function commandHelpByKey(key) {
       usage: "image-skill doctor --json",
       docs_url: "https://image-skill.com/cli.md#image-skill-doctor",
       description:
-        "Check hosted API reachability, CLI version, auth state, and health.",
+        "Check hosted API reachability, CLI version, auth state, health, and live-spend recovery breadcrumbs.",
+      optional_flags: ["--sweep-in-flight"],
     },
     trust: {
       command: "image-skill trust help",
@@ -518,6 +532,7 @@ function commandHelpByKey(key) {
       docs_url: "https://image-skill.com/cli.md#image-skill-edit",
       required_flags: ["--input"],
       optional_flags: [
+        "--guide",
         "--dry-run",
         "--prompt",
         "--model",
@@ -606,6 +621,10 @@ async function doctor(argv) {
   const args = parseArgs(argv);
   const apiBaseUrl = apiBase(args);
   const config = await readConfig(configPath());
+  const inFlight = await inFlightSpendDoctorReport({
+    sweep: flagBool(args, "sweep-in-flight"),
+    now: new Date(),
+  });
   const health = await apiRequest({
     command: "image-skill doctor",
     method: "GET",
@@ -628,6 +647,7 @@ async function doctor(argv) {
       saved_token: config.tokenPresent,
       env_token: hasEnvToken(),
     },
+    in_flight: inFlight,
     docs: {
       skill: "https://image-skill.com/skill.md",
       llms: "https://image-skill.com/llms.txt",
@@ -1591,17 +1611,19 @@ async function capabilities(argv) {
   });
 }
 
-async function createGuide(args) {
+async function createGuide(args, options = {}) {
+  const guideOperation = options.guideOperation ?? "create";
+  const command = `image-skill ${guideOperation} --guide`;
   if (flagBool(args, "dry-run")) {
     return invalid(
-      "image-skill create --guide",
-      "create --guide cannot be combined with --dry-run; the guide returns the dry-run escape hatch separately",
+      command,
+      `${guideOperation} --guide cannot be combined with --dry-run; the guide returns the dry-run escape hatch separately`,
     );
   }
   if (hasReferenceFlags(args)) {
     return invalid(
-      "image-skill create --guide",
-      "create --guide does not upload or resolve reference images; inspect the model with models show, then run create --dry-run before live referenced creates",
+      command,
+      `${guideOperation} --guide does not upload or resolve reference images; inspect the model with models show, then run ${guideOperation} --dry-run before live referenced media calls`,
     );
   }
   const modelParameters = jsonObjectFlag(args, "model-parameters-json");
@@ -1616,6 +1638,10 @@ async function createGuide(args) {
   const requestedProviderId = flagString(args, "provider");
   const requestedIntentFlag = flagString(args, "intent");
   const requestedIntent = requestedIntentFlag ?? "explore";
+  const requestedModelParametersJson =
+    modelParameters.value === null
+      ? null
+      : JSON.stringify(modelParameters.value);
   const maxEstimatedUsdPerImage = flagNumber(
     args,
     "max-estimated-usd-per-image",
@@ -1646,17 +1672,58 @@ async function createGuide(args) {
   const selected =
     models.envelope.ok && models.envelope.data?.models
       ? selectCreateGuideModel(models.envelope.data.models, requestedModelId, {
+          operation: guideOperation,
           prompt: trimmedPrompt,
           intent: requestedIntent,
           maxEstimatedUsdPerImage,
         })
       : null;
   const selectedAspectRatio = createGuideSuggestedAspectRatio(selected);
-  const pricing = createGuideModelCreditPricing(selected);
+  const pricingContext = {
+    aspectRatio: selectedAspectRatio ?? "1:1",
+    outputCount: 1,
+  };
+  const defaultedModelParameters =
+    selected === null || createGuideSelectedModelRequiresInputImage(selected)
+      ? {
+          modelParameters: modelParameters.value ?? {},
+          defaultsApplied: [],
+        }
+      : createGuideDefaultModelParameters({
+          model: selected,
+          aspectRatio: pricingContext.aspectRatio,
+          intent: requestedIntent,
+          modelParameters: modelParameters.value ?? {},
+          maxEstimatedUsdPerImage,
+        });
+  const shouldPriceModelParameters =
+    selected !== null &&
+    !createGuideSelectedModelRequiresInputImage(selected) &&
+    createGuideCanPriceModelParameters(selected) &&
+    (defaultedModelParameters.defaultsApplied.length > 0 ||
+      Object.keys(modelParameters.value ?? {}).length > 0);
+  const pricing =
+    selected === null
+      ? null
+      : shouldPriceModelParameters
+        ? createGuidePricingForModel(
+            selected,
+            defaultedModelParameters.modelParameters,
+            pricingContext,
+          )
+        : createGuideModelCreditPricing(selected);
+  const providerCostEstimate =
+    selected === null || !shouldPriceModelParameters
+      ? null
+      : createGuideProviderCostEstimateForModel(
+          selected,
+          defaultedModelParameters.modelParameters,
+          pricingContext,
+        );
   const estimatedCredits = pricing?.credits_required ?? null;
   const estimatedProviderUsdPerImage =
+    providerCostEstimate?.estimated_provider_cost_usd ??
     selected?.economics?.estimated_usd_per_image ??
-    pricing?.estimated_provider_cost_usd ??
     pricing?.fallback_provider_cost_usd ??
     (typeof selected?.estimated_usd_per_image === "number"
       ? selected.estimated_usd_per_image
@@ -1683,6 +1750,9 @@ async function createGuide(args) {
     token.source === "anonymous" ? "none" : token.source;
   const stage = createGuideStage({
     prompt: trimmedPrompt,
+    promptRequired:
+      trimmedPrompt.length === 0 &&
+      (selected === null || !PROMPTLESS_EDIT_MODEL_IDS.has(selected.id)),
     health,
     models,
     selected,
@@ -1714,9 +1784,12 @@ async function createGuide(args) {
     requestedIntent,
     requestedIntentFlag,
     requestedModelId,
+    guideOperation,
+    inputReference: options.inputReference,
     maxEstimatedUsdPerImage,
     budgetGuard,
     aspectRatio: selectedAspectRatio,
+    modelParametersJson: requestedModelParametersJson,
     apiBaseUrl: explicitApiBaseUrl(args),
     paymentSummary,
     commandPrefix: guideCommandPrefix,
@@ -1732,9 +1805,12 @@ async function createGuide(args) {
     requestedIntent,
     requestedIntentFlag,
     requestedModelId,
+    guideOperation,
+    inputReference: options.inputReference,
     maxEstimatedUsdPerImage,
     budgetGuard,
     aspectRatio: selectedAspectRatio,
+    modelParametersJson: requestedModelParametersJson,
     apiBaseUrl: explicitApiBaseUrl(args),
     commandPrefix: guideCommandPrefix,
   });
@@ -1776,10 +1852,13 @@ async function createGuide(args) {
           explicitApiBaseUrl(args),
           guideCommandPrefix,
           {
+            operation: guideOperation,
+            inputReference: options.inputReference,
             modelId: requestedModelId,
             providerId: requestedProviderId,
             intent: requestedIntentFlag,
             maxEstimatedUsdPerImage,
+            modelParametersJson: requestedModelParametersJson,
           },
         )
       : null;
@@ -1802,8 +1881,19 @@ async function createGuide(args) {
     tokenSource: publicTokenSource,
     commandPrefix: guideCommandPrefix,
   });
-  return createGuideSuccess(quota?.envelope.actor ?? null, {
-    schema: "image-skill.create-guide.v1",
+  const guideRecovery = createGuideRecovery(stage, {
+    blocker,
+    nextCommand,
+    noSpendNextCommand,
+    afterNext,
+    escapeHatches,
+    selfFundNextCommand,
+  });
+  return createGuideSuccess(command, quota?.envelope.actor ?? null, {
+    schema:
+      guideOperation === "edit"
+        ? "image-skill.edit-guide.v1"
+        : "image-skill.create-guide.v1",
     ready: stage === "ready_to_create",
     stage,
     checks: {
@@ -1868,6 +1958,7 @@ async function createGuide(args) {
                     selected,
                     trimmedPrompt,
                     requestedIntent,
+                    guideOperation,
                   )
                 : createGuideSelectedModelRequiresInputImage(selected)
                   ? selected.modality === "3d"
@@ -1882,6 +1973,9 @@ async function createGuide(args) {
       estimated_provider_usd_per_image: estimatedProviderUsdPerImage,
       credit_unit_usd: pricing?.credit_unit_usd ?? CREDIT_UNIT_USD,
       pricing_confidence: pricing?.pricing_confidence ?? null,
+      pricing_source: pricing?.pricing_source ?? null,
+      model_parameter_defaults_applied:
+        defaultedModelParameters.defaultsApplied,
     },
     blocker,
     guide_warning: guideWarning,
@@ -1894,6 +1988,7 @@ async function createGuide(args) {
     no_spend_next_command_label: noSpendNextCommandLabel,
     no_spend_next_command_effect: noSpendNextCommandEffect,
     no_spend_evaluation: noSpendEvaluation,
+    guide_recovery: guideRecovery,
     recommended_no_spend_command: noSpendNextCommand,
     recommended_no_spend_command_label: noSpendNextCommandLabel,
     recommended_no_spend_command_effect: noSpendNextCommandEffect,
@@ -1914,8 +2009,8 @@ async function createGuide(args) {
   });
 }
 
-function createGuideSuccess(actor, data) {
-  const result = success("image-skill create --guide", data);
+function createGuideSuccess(command, actor, data) {
+  const result = success(command, data);
   result.envelope.actor = actor;
   return result;
 }
@@ -1923,7 +2018,12 @@ function createGuideSuccess(actor, data) {
 function selectCreateGuideModel(
   models,
   requestedModelId,
-  { prompt = "", intent = undefined, maxEstimatedUsdPerImage = null } = {},
+  {
+    operation = "create",
+    prompt = "",
+    intent = undefined,
+    maxEstimatedUsdPerImage = null,
+  } = {},
 ) {
   const isExecutableCreate = (model) =>
     model?.status === "available" &&
@@ -1937,14 +2037,19 @@ function selectCreateGuideModel(
     (model.supports.includes("edit") || model.supports.includes("variation")) &&
     createGuideSelectedModelRequiresInputImage(model);
   const isExecutableGuideModel = (model) =>
-    isExecutableCreate(model) || isExecutableInputImageEdit(model);
+    operation === "edit"
+      ? isExecutableInputImageEdit(model)
+      : isExecutableCreate(model) || isExecutableInputImageEdit(model);
   if (requestedModelId !== null) {
     const requested = models.find((model) => model.id === requestedModelId);
     return requested !== undefined && isExecutableGuideModel(requested)
       ? requested
       : null;
   }
-  const candidates = models.filter(isExecutableCreate);
+  const candidates =
+    operation === "edit"
+      ? models.filter(isExecutableInputImageEdit)
+      : models.filter(isExecutableCreate);
   if (createGuideImplies3d({ prompt, intent })) {
     const eligible3d = guideCandidatesWithinBudget({
       candidates: models.filter(
@@ -2052,6 +2157,221 @@ function guideBudgetUsdForModel(model) {
   );
 }
 
+function createGuideDefaultModelParameters(input) {
+  const modelParameters = { ...(input.modelParameters ?? {}) };
+  const defaultsApplied = [];
+
+  if (
+    input.model?.id === "xai.grok-imagine-image-quality" &&
+    modelParameters.resolution === undefined
+  ) {
+    const twoKEstimate = createGuideProviderCostEstimateForModel(
+      input.model,
+      { resolution: "2k" },
+      { aspectRatio: input.aspectRatio },
+    ).estimated_provider_cost_usd;
+    const twoKAllowedByBudget =
+      input.maxEstimatedUsdPerImage === null ||
+      twoKEstimate === null ||
+      twoKEstimate <= input.maxEstimatedUsdPerImage;
+    const intentClass = createGuideIntentClass(input.intent);
+    const resolution =
+      intentClass !== "budget_draft" && twoKAllowedByBudget ? "2k" : "1k";
+    modelParameters.resolution = resolution;
+    defaultsApplied.push(`resolution=${resolution}`);
+  }
+
+  if (
+    input.model?.id === "fal.flux-dev" &&
+    modelParameters.image_size === undefined
+  ) {
+    const imageSize = falDefaultImageSize(input.aspectRatio);
+    if (imageSize !== null) {
+      modelParameters.image_size = imageSize;
+      defaultsApplied.push(`image_size=${imageSize}`);
+    }
+  }
+
+  if (
+    input.model?.id === "openai.gpt-image-2" &&
+    modelParameters.quality === undefined
+  ) {
+    const mediumEstimate = createGuideProviderCostEstimateForModel(
+      input.model,
+      { ...modelParameters, quality: "medium" },
+      { aspectRatio: input.aspectRatio },
+    ).estimated_provider_cost_usd;
+    const mediumAllowedByBudget =
+      input.maxEstimatedUsdPerImage === null ||
+      mediumEstimate === null ||
+      mediumEstimate <= input.maxEstimatedUsdPerImage;
+    if (mediumAllowedByBudget) {
+      modelParameters.quality = "medium";
+      defaultsApplied.push("quality=medium");
+    }
+  }
+
+  return { modelParameters, defaultsApplied };
+}
+
+function createGuidePricingForModel(model, modelParameters, context = {}) {
+  const estimate = createGuideProviderCostEstimateForModel(
+    model,
+    modelParameters,
+    context,
+  );
+  if (estimate.estimated_provider_cost_usd === null) {
+    return createGuideModelCreditPricing(model);
+  }
+  return createGuideCreditPricingForProviderCost({
+    providerCostUsd: estimate.estimated_provider_cost_usd,
+    pricingConfidence: estimate.pricing_confidence,
+    pricingSource: estimate.pricing_source,
+  });
+}
+
+function createGuideCanPriceModelParameters(model) {
+  return String(model?.id ?? "").startsWith("xai.grok-imagine-image");
+}
+
+function createGuideProviderCostEstimateForModel(
+  model,
+  modelParameters = {},
+  context = {},
+) {
+  if (String(model?.id ?? "").startsWith("xai.grok-imagine-image")) {
+    return createGuideXaiImageCostEstimate(model, modelParameters, context);
+  }
+  return {
+    estimated_provider_cost_usd:
+      typeof model?.economics?.estimated_usd_per_image === "number"
+        ? model.economics.estimated_usd_per_image
+        : (createGuideModelCreditPricing(model)?.estimated_provider_cost_usd ??
+          null),
+    pricing_source: "model_registry",
+    pricing_confidence: "known",
+  };
+}
+
+function createGuideXaiImageCostEstimate(model, modelParameters, context) {
+  const modelId = String(model?.id ?? "");
+  const quality = modelId.includes("-quality");
+  const edit = modelId.endsWith("-edit");
+  const resolution = modelParameters?.resolution === "2k" ? "2k" : "1k";
+  const outputImageCount =
+    Number.isInteger(context?.outputCount) && context.outputCount > 0
+      ? context.outputCount
+      : 1;
+  const referenceAssetCount =
+    Number.isInteger(context?.referenceAssetCount) &&
+    context.referenceAssetCount > 0
+      ? context.referenceAssetCount
+      : 0;
+  const sourceImageCount = edit ? 1 + referenceAssetCount : 0;
+  const inputUsdPerImage = quality ? 0.01 : 0.002;
+  const outputUsdPerImage =
+    quality && resolution === "2k" ? 0.07 : quality ? 0.05 : 0.02;
+  const defaultResolution =
+    modelParameters?.resolution === undefined ||
+    modelParameters?.resolution === null ||
+    modelParameters?.resolution === "1k";
+  const defaultShape =
+    defaultResolution &&
+    outputImageCount === 1 &&
+    sourceImageCount === (edit ? 1 : 0);
+  return {
+    estimated_provider_cost_usd: roundUsdMicro(
+      inputUsdPerImage * sourceImageCount +
+        outputUsdPerImage * outputImageCount,
+    ),
+    pricing_source: defaultShape ? "model_registry" : "model_parameters",
+    pricing_confidence: "known",
+  };
+}
+
+function createGuideCreditPricingForProviderCost(input) {
+  const providerCostUsd = roundUsdMicro(input.providerCostUsd);
+  const creditsRequired = Math.max(
+    1,
+    Math.ceil(
+      roundUsdMicro(
+        providerCostUsd / (1 - TARGET_GROSS_MARGIN) / CREDIT_UNIT_USD,
+      ),
+    ),
+  );
+  const estimatedRevenueUsd = roundUsd(creditsRequired * CREDIT_UNIT_USD);
+  const estimatedPaymentFeeUsd = roundUsdMicro(
+    estimatedRevenueUsd * PAYMENT_BACKED_CREDIT_PAYMENT_FEE_RATE,
+  );
+  const estimatedNetRevenueUsd = roundUsdMicro(
+    estimatedRevenueUsd - estimatedPaymentFeeUsd,
+  );
+  const estimatedGrossMargin =
+    estimatedRevenueUsd > 0
+      ? roundRatio(
+          (estimatedRevenueUsd - providerCostUsd) / estimatedRevenueUsd,
+        )
+      : null;
+  const estimatedFeeAdjustedMargin =
+    estimatedRevenueUsd > 0
+      ? roundRatio(
+          (estimatedNetRevenueUsd - providerCostUsd) / estimatedRevenueUsd,
+        )
+      : null;
+  const selfFundBlockReason =
+    estimatedNetRevenueUsd + 1e-9 < providerCostUsd
+      ? "payment_fee_margin_negative"
+      : null;
+  return {
+    credits_required: creditsRequired,
+    credit_unit_usd: CREDIT_UNIT_USD,
+    estimated_provider_cost_usd: providerCostUsd,
+    fallback_provider_cost_usd: null,
+    estimated_revenue_usd: estimatedRevenueUsd,
+    estimated_gross_margin: estimatedGrossMargin,
+    payment_fee_rate: PAYMENT_BACKED_CREDIT_PAYMENT_FEE_RATE,
+    payment_fee_model: PAYMENT_BACKED_CREDIT_PAYMENT_FEE_MODEL,
+    estimated_payment_fee_usd: estimatedPaymentFeeUsd,
+    estimated_net_revenue_usd: estimatedNetRevenueUsd,
+    estimated_fee_adjusted_margin: estimatedFeeAdjustedMargin,
+    self_fundable: selfFundBlockReason === null,
+    self_fund_block_reason: selfFundBlockReason,
+    target_gross_margin: TARGET_GROSS_MARGIN,
+    pricing_confidence: input.pricingConfidence,
+    pricing_source: input.pricingSource,
+    margin_model: "provider_cost_plus_margin",
+  };
+}
+
+function falDefaultImageSize(aspectRatio) {
+  switch (aspectRatio) {
+    case "1:1":
+      return "square_hd";
+    case "4:3":
+      return "landscape_4_3";
+    case "3:4":
+      return "portrait_4_3";
+    case "16:9":
+      return "landscape_16_9";
+    case "9:16":
+      return "portrait_16_9";
+    default:
+      return null;
+  }
+}
+
+function roundUsd(value) {
+  return Math.round(value * 100) / 100;
+}
+
+function roundRatio(value) {
+  return Math.round(value * 1000) / 1000;
+}
+
+function roundUsdMicro(value) {
+  return Math.round(value * 1_000_000) / 1_000_000;
+}
+
 function guideModelExecutionStatus(model) {
   if (
     isRecord(model?.execution) &&
@@ -2139,7 +2459,12 @@ function createGuideSelectedModelRequiresInputImage(model) {
   );
 }
 
-function createGuideSelectionReason(model, prompt, intent) {
+function createGuideSelectionReason(
+  model,
+  prompt,
+  intent,
+  operation = "create",
+) {
   if (
     createGuideSelectedModelRequiresInputImage(model) &&
     createGuideImplies3d({ prompt, intent })
@@ -2167,7 +2492,9 @@ function createGuideSelectionReason(model, prompt, intent) {
       ? "guide selected a draft/budget create model with high-definition defaults"
       : "guide selected the strongest currently available quality-first create model for this intent";
   }
-  return "guide selected the first available executable create model";
+  return operation === "edit"
+    ? "guide selected the first available executable input-image edit model"
+    : "guide selected the first available executable create model";
 }
 
 function createGuidePaymentSummary(data, commandPrefix) {
@@ -2382,7 +2709,7 @@ function renderCopyRunnablePaymentCommand(commandPrefix, command) {
 }
 
 function createGuideStage(input) {
-  if (input.prompt.length === 0) {
+  if (input.promptRequired) {
     return "prompt_required";
   }
   if (!input.health.envelope.ok || !input.models.envelope.ok) {
@@ -2789,6 +3116,64 @@ function createGuideNoSpendEvaluation(stage, input) {
   };
 }
 
+function createGuideRecovery(stage, input) {
+  let noSpendCommand = null;
+  let noSpendCommandField = null;
+  if (stage === "ready_to_create" && input.noSpendNextCommand !== null) {
+    noSpendCommand = input.noSpendNextCommand;
+    noSpendCommandField = "recommended_no_spend_command";
+  } else if (stage === "quota_required") {
+    noSpendCommand = input.escapeHatches.quota;
+    noSpendCommandField = "escape_hatches.quota";
+  } else if (
+    stage === "no_executable_model" ||
+    stage === "service_unreachable"
+  ) {
+    noSpendCommand = input.nextCommand;
+    noSpendCommandField = "next_command";
+  } else if (stage === "auth_required" || stage === "prompt_required") {
+    noSpendCommand = input.nextCommand;
+    noSpendCommandField = "next_command";
+  }
+  const noSpendMissingInputs =
+    noSpendCommand === null
+      ? []
+      : createGuideNextCommandMissingInputs(noSpendCommand);
+  const liveCreateCommandField =
+    stage === "ready_to_create" ? "next_command" : null;
+  const livePaymentCommandField =
+    stage === "quota_required" && input.selfFundNextCommand !== null
+      ? "self_fund_next_command"
+      : null;
+  const doubleSpendGuardRequired =
+    liveCreateCommandField !== null || livePaymentCommandField !== null;
+  return {
+    schema: "image-skill.guide-recovery.v1",
+    stage,
+    precondition_code: input.blocker?.code ?? null,
+    precondition_message: input.blocker?.message ?? null,
+    no_spend_command: noSpendCommand,
+    no_spend_command_field: noSpendCommandField,
+    no_spend_command_copy_runnable:
+      noSpendCommand === null ? null : noSpendMissingInputs.length === 0,
+    no_spend_command_missing_inputs: noSpendMissingInputs,
+    after_success_command: input.afterNext,
+    after_success_command_field: input.afterNext === null ? null : "after_next",
+    live_create_command_field: liveCreateCommandField,
+    live_payment_command_field: livePaymentCommandField,
+    double_spend_guard: {
+      required: doubleSpendGuardRequired,
+      safe_rerun_command_field: noSpendCommandField,
+      warning:
+        liveCreateCommandField !== null
+          ? "Do not blindly rerun data.next_command after a partial or unknown create/edit failure; use data.guide_recovery.no_spend_command, jobs/activity, or error.recovery before any live retry."
+          : livePaymentCommandField !== null
+            ? "Do not blindly rerun live payment commands with fresh identifiers after a partial or unknown payment failure; use data.guide_recovery.no_spend_command and payment status recovery before any new buy."
+            : "No live payment or live media command is exposed for this stage; follow the no-spend command and rerun the guide after the precondition is satisfied.",
+    },
+  };
+}
+
 function createGuideWarning(stage, input) {
   const effect = input.nextCommandEffect;
   const base = {
@@ -2909,10 +3294,13 @@ function escapeRegExp(value) {
 function createGuideNextCommand(stage, input) {
   if (stage === "prompt_required") {
     return renderGuideCommand("PROMPT", input.apiBaseUrl, input.commandPrefix, {
+      operation: input.guideOperation,
+      inputReference: input.inputReference,
       modelId: input.requestedModelId,
       providerId: input.requestedProviderId,
       intent: input.requestedIntentFlag,
       maxEstimatedUsdPerImage: input.maxEstimatedUsdPerImage,
+      modelParametersJson: input.modelParametersJson,
     });
   }
   if (stage === "no_executable_model" || stage === "service_unreachable") {
@@ -2934,7 +3322,9 @@ function createGuideNextCommand(stage, input) {
     return renderInputImageGuideCommand({
       modelId: input.selected.id,
       prompt: input.prompt,
+      inputReference: input.inputReference,
       budgetGuard: input.budgetGuard,
+      modelParametersJson: input.modelParametersJson,
       dryRun: false,
       idempotencyKey: `edit-guide-${Date.now()}-${randomBytes(4).toString("hex")}`,
       apiBaseUrl: input.apiBaseUrl,
@@ -2948,6 +3338,7 @@ function createGuideNextCommand(stage, input) {
     intent: input.requestedIntent,
     budgetGuard: input.budgetGuard,
     aspectRatio: input.aspectRatio,
+    modelParametersJson: input.modelParametersJson,
     dryRun: false,
     // Retry-safe by default (#1228): bake a stable idempotency key into the
     // advertised create command so an agent that copies it and retries after a
@@ -2977,16 +3368,22 @@ function createGuideEscapeHatches(input) {
       "usage quota --json",
     ),
     dry_run:
-      input.selected === null || input.prompt.length === 0
+      input.selected === null ||
+      (input.prompt.length === 0 &&
+        !PROMPTLESS_EDIT_MODEL_IDS.has(input.selected.id))
         ? renderGuidePrefixedCommand(
             input.commandPrefix,
-            "create --dry-run --prompt PROMPT --json",
+            input.guideOperation === "edit"
+              ? "edit --dry-run --input image_... --prompt PROMPT --json"
+              : "create --dry-run --prompt PROMPT --json",
           )
         : createGuideSelectedModelRequiresInputImage(input.selected)
           ? renderInputImageGuideCommand({
               modelId: input.selected.id,
               prompt: input.prompt,
+              inputReference: input.inputReference,
               budgetGuard: input.budgetGuard,
+              modelParametersJson: input.modelParametersJson,
               dryRun: true,
               apiBaseUrl: input.apiBaseUrl,
               commandPrefix: input.commandPrefix,
@@ -2998,6 +3395,7 @@ function createGuideEscapeHatches(input) {
               intent: input.requestedIntent,
               budgetGuard: input.budgetGuard,
               aspectRatio: input.aspectRatio,
+              modelParametersJson: input.modelParametersJson,
               dryRun: true,
               apiBaseUrl: input.apiBaseUrl,
               commandPrefix: input.commandPrefix,
@@ -3011,10 +3409,16 @@ function renderGuideCommand(
   commandPrefix = "image-skill",
   options = {},
 ) {
+  const operation = options.operation ?? "create";
   return [
     commandPrefix,
-    "create --guide --prompt",
+    `${operation} --guide --prompt`,
     shellQuote(prompt),
+    ...(operation === "edit" &&
+    typeof options.inputReference === "string" &&
+    options.inputReference.trim().length > 0
+      ? ["--input", shellQuote(options.inputReference.trim())]
+      : []),
     ...(options.modelId === null ||
     options.modelId === undefined ||
     options.modelId === ""
@@ -3037,6 +3441,10 @@ function renderGuideCommand(
           "--max-estimated-usd-per-image",
           shellQuote(formatUsd(options.maxEstimatedUsdPerImage)),
         ]),
+    ...(options.modelParametersJson === null ||
+    options.modelParametersJson === undefined
+      ? []
+      : ["--model-parameters-json", shellQuote(options.modelParametersJson)]),
     ...(apiBaseUrl === null ? [] : ["--api-base-url", shellQuote(apiBaseUrl)]),
     "--json",
   ].join(" ");
@@ -3091,12 +3499,18 @@ function renderInputImageGuideCommand(input) {
     "edit",
     ...(input.dryRun ? ["--dry-run"] : []),
     "--input",
-    "image_...",
+    input.inputReference?.trim()
+      ? shellQuote(input.inputReference.trim())
+      : "image_...",
     "--model",
     shellQuote(input.modelId),
     ...(promptless ? [] : ["--prompt", shellQuote(input.prompt)]),
     "--max-estimated-usd-per-image",
     shellQuote(formatUsd(input.budgetGuard)),
+    ...(input.modelParametersJson === null ||
+    input.modelParametersJson === undefined
+      ? []
+      : ["--model-parameters-json", shellQuote(input.modelParametersJson)]),
     ...(input.idempotencyKey === undefined || input.idempotencyKey === null
       ? []
       : ["--idempotency-key", shellQuote(input.idempotencyKey)]),
@@ -3126,6 +3540,10 @@ function renderCreateCommand(input) {
       : ["--aspect-ratio", shellQuote(input.aspectRatio)]),
     "--max-estimated-usd-per-image",
     shellQuote(formatUsd(input.budgetGuard)),
+    ...(input.modelParametersJson === null ||
+    input.modelParametersJson === undefined
+      ? []
+      : ["--model-parameters-json", shellQuote(input.modelParametersJson)]),
     ...(input.idempotencyKey === undefined || input.idempotencyKey === null
       ? []
       : ["--idempotency-key", shellQuote(input.idempotencyKey)]),
@@ -3361,6 +3779,12 @@ async function edit(argv) {
   const args = parseArgs(argv);
   const input = flagString(args, "input") ?? args.positionals[0];
   const modelId = flagString(args, "model");
+  if (flagBool(args, "guide")) {
+    return createGuide(args, {
+      guideOperation: "edit",
+      inputReference: input,
+    });
+  }
   if (input === undefined) {
     return invalid(
       "image-skill edit",
@@ -4575,6 +4999,169 @@ function inFlightSpendFileName(idempotencyKey) {
   return `${trimmed.length === 0 ? "key" : trimmed}.json`;
 }
 
+async function inFlightSpendDoctorReport(input) {
+  const dir = inFlightSpendDir();
+  const now = input.now ?? new Date();
+  const files = await readdir(dir).catch((error) => {
+    if (error?.code === "ENOENT") {
+      return [];
+    }
+    return null;
+  });
+  if (files === null) {
+    return {
+      schema: "image-skill.in-flight-spend-report.v1",
+      directory: dir,
+      count: null,
+      recoverable_count: null,
+      ttl_elapsed_count: null,
+      sweep_eligible_count: null,
+      invalid_count: null,
+      entries: [],
+      error: "in-flight directory could not be read",
+      reservation_ttl_ms: IN_FLIGHT_RESERVATION_TTL_MS,
+      sweep_after_ms: IN_FLIGHT_SWEEP_AFTER_MS,
+      swept_count: 0,
+      sweep_requested: input.sweep === true,
+    };
+  }
+
+  const entries = [];
+  let invalidCount = 0;
+  let sweptCount = 0;
+  for (const file of files.sort()) {
+    if (!file.endsWith(".json")) {
+      continue;
+    }
+    const path = join(dir, file);
+    const entry = await readInFlightSpendEntry({ path, file, now });
+    if (entry === null) {
+      invalidCount += 1;
+      continue;
+    }
+    if (input.sweep === true && entry.sweep_eligible === true) {
+      await rm(path, { force: true }).catch(() => {});
+      sweptCount += 1;
+      continue;
+    }
+    entries.push(entry);
+  }
+
+  return {
+    schema: "image-skill.in-flight-spend-report.v1",
+    directory: dir,
+    count: entries.length,
+    recoverable_count: entries.filter((entry) => entry.state === "recoverable")
+      .length,
+    ttl_elapsed_count: entries.filter((entry) => entry.state === "ttl_elapsed")
+      .length,
+    sweep_eligible_count: entries.filter((entry) => entry.sweep_eligible)
+      .length,
+    invalid_count: invalidCount,
+    swept_count: sweptCount,
+    reservation_ttl_ms: IN_FLIGHT_RESERVATION_TTL_MS,
+    sweep_after_ms: IN_FLIGHT_SWEEP_AFTER_MS,
+    sweep_requested: input.sweep === true,
+    entries,
+    note:
+      entries.length === 0
+        ? "no in-flight live spend breadcrumbs found"
+        : "rerun an entry's recover_command to settle or inspect a maybe-reserved spend before sweeping it",
+  };
+}
+
+async function readInFlightSpendEntry({ path, file, now }) {
+  let parsed;
+  let fileStat;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+    fileStat = await stat(path);
+  } catch {
+    return null;
+  }
+  if (
+    parsed?.schema !== "image-skill.in-flight-spend.v1" ||
+    typeof parsed.idempotency_key !== "string" ||
+    typeof parsed.operation !== "string"
+  ) {
+    return null;
+  }
+
+  const startedAt =
+    typeof parsed.started_at === "string" ? parsed.started_at : null;
+  const startedTime =
+    startedAt === null ? Number.NaN : new Date(startedAt).getTime();
+  const fallbackTime = fileStat.mtime.getTime();
+  const basisTime = Number.isFinite(startedTime) ? startedTime : fallbackTime;
+  const ageMs = Math.max(0, now.getTime() - basisTime);
+  const state =
+    ageMs >= IN_FLIGHT_RESERVATION_TTL_MS ? "ttl_elapsed" : "recoverable";
+  const sweepEligible = ageMs >= IN_FLIGHT_SWEEP_AFTER_MS;
+  const argv = Array.isArray(parsed.argv)
+    ? parsed.argv.filter((value) => typeof value === "string")
+    : [];
+  const recoverCommand = renderRecoverCommand({
+    operation: parsed.operation,
+    argv,
+    idempotencyKey: parsed.idempotency_key,
+    fallback: parsed.recover_command,
+  });
+
+  return {
+    file,
+    path,
+    operation: parsed.operation,
+    command:
+      typeof parsed.command === "string"
+        ? parsed.command
+        : `image-skill ${parsed.operation}`,
+    idempotency_key: parsed.idempotency_key,
+    started_at: startedAt,
+    age_ms: ageMs,
+    state,
+    sweep_eligible: sweepEligible,
+    recover_command: recoverCommand,
+    original_recover_command:
+      typeof parsed.recover_command === "string"
+        ? parsed.recover_command
+        : null,
+    warning:
+      state === "recoverable"
+        ? "the hosted reservation TTL has not elapsed; recover before cleanup"
+        : sweepEligible
+          ? "reservation TTL has long elapsed; recover first if the original result still matters, or run doctor --sweep-in-flight to remove this breadcrumb"
+          : "reservation TTL has elapsed; recover if you need the result, otherwise leave it until it becomes sweep-eligible",
+  };
+}
+
+function renderRecoverCommand(input) {
+  const argv = withRecoveryArgs(input.argv, input.idempotencyKey);
+  if (argv.length === 0 && typeof input.fallback === "string") {
+    return input.fallback;
+  }
+  return renderImageSkillCommand(input.operation, argv);
+}
+
+function withRecoveryArgs(argv, idempotencyKey) {
+  const args = [...argv];
+  const hasIdempotency = args.some(
+    (arg) =>
+      arg === "--idempotency-key" || arg.startsWith("--idempotency-key="),
+  );
+  if (!hasIdempotency) {
+    args.push("--idempotency-key", idempotencyKey);
+  }
+  const hasJson = args.some((arg) => arg === "--json");
+  if (!hasJson) {
+    args.push("--json");
+  }
+  return args;
+}
+
+function renderImageSkillCommand(operation, argv) {
+  return ["image-skill", operation, ...argv.map(shellQuote)].join(" ");
+}
+
 async function recordInFlightSpend(input) {
   const { command, operation, idempotencyKey, argv } = input;
   const recoverCommand = recoverCommandFor(operation, idempotencyKey);