Naming background tasks so re-runs reuse them

task_name is not a label for this run. Every spawn_background_task auto-creates a reusable saved workflow keyed on that string. Re-spawn with the same name and the platform reuses the existing step-based workflow row instead of inserting a v2. Name the run ("Vlog Rerun v2", "from Upload", "Attempt 3", Tuesday's product) and you get a workflows list full of near-duplicates, none of which is obviously the recipe you meant.

The handle you want is the intent: three to six words, Title Case, describing what the workflow produces. "Instagram Vlog with Captions". "Product Reel from Photo". "Daily Tech News Post". Then a re-run is one instruction: run that again.

Name by intent, not by this morning

The tool's own naming rules are specific enough to treat as a style guide.

Do

• Title Case, 3–6 words.
• Describe the outcome: format, platform, finishing. "AI Movie with Soundtrack" is a recipe. "Sora 2 Movie" is acceptable only if the model is the defining feature.
• Match an existing name if a similar workflow already lives in the account. Call list_user_workflows first when you are not sure.

Do not

• Put run-specific noise in the name: "Rerun", "v2", "Again", "from Upload", "Attempt 3", timestamps, the exact prompt text.
• Put the model name in unless the model is the product of the recipe. "LTX 2.3 Vlog Rerun v2" is three mistakes in one string. The recipe is "Vlog Reel with Captions".
• Put nouns that change every run: a product SKU, a date, this week's caption.

Matching is exact and case-sensitive on name. "Instagram Vlog with Captions" and "instagram vlog with captions" are two workflows. Pick one spelling and keep it. The saved-workflow screen is the same list you get from saving and reusing a video workflow; spawn is just the way a chat turn writes into it.

A recurring series makes the cost of a bad name obvious. You are going to ask for "the vlog" forty times. If each ask minted a new row, you would have forty recipes and no series.

What reuse actually does

On spawn, if you did not pass a workflow_id, the backend looks up a step-based workflow with this exact task_name for this user.

• Hit, and it is a step workflow. The existing row is reused. run_count goes up. last_run_at updates. A new background_tasks row still appears (this run), but the recipe identity stays one row. Empty or placeholder descriptions can be filled in; a theme you already set is not overwritten.
• Hit, but it is a scene workflow (a scenes array with length greater than zero). Reuse is skipped. A new step-workflow row is inserted under the same name, so you now have two recipes with one handle. Re-run scene workflows with run_workflow, not by spawning steps onto the same name.
• Miss. A new user_workflows row is inserted. description becomes your workflow_theme if you sent one, or the placeholder Auto-created from chat: N steps if you did not.

That last fallback is how recipes drift. A placeholder is not a brief. The next re-run has nothing stable to honour, so the model writes a new prompt from whatever you said this time. Always send workflow_theme on the first spawn. One to three sentences: who or what stays constant, the visual style, the format, any recurring motif. Not the exact caption, not today's date, not "v2".

Field	Job	Failure if you skip it
task_name	Identity of the auto-saved workflow	Duplicate rows, or a miss because you changed the spelling
workflow_theme	Stable brief, stored as description	Re-runs wander off the original look
steps	What this run actually executes	You have a name and no recipe
media_assets	Files later steps address as $assets.0.url or $assets_by_label.product_photo	The recipe cannot be reused against a new product photo

Theme and name do different jobs. The name is the handle you type. The theme is what the workflows list will show as the description, and what the agent is told to re-read when you say "run that again."

The re-run sequence

When you mean "again," do not invent a new name. The prescribed sequence is:

1. list_user_workflows. Find the row. Read description. That string is a hard constraint.
2. If the row is a scene workflow, call run_workflow with its workflow_id. Freshness is on by default for later runs: a new plot, same characters, assets, and style. The first run always plays the scenes you approved.
3. If the row is a step workflow, spawn again with the same task_name and the same workflow_theme. Build new steps that produce fresh content. Prefer an ai_generate_prompt step at index 0 whose prompt_instruction embeds the theme, then point later generate/post steps at $step_0.generated.prompt, $step_0.generated.caption, and so on.

That last point is enforced. If the reused workflow has a real theme (not the auto-created placeholder) and has been run before, a spawn whose steps still contain literal prompts and captions from last time is rejected. The error tells you to prepend ai_generate_prompt and rewrite the literals to $step_0.generated.*. If you truly want an identical replay, the escape hatch is a different task_name, so you are not matching the themed row.

First-run prompt that sets this up correctly:

Spawn a background task named "Instagram Vlog with Captions". Theme: young blonde vlogger in city streetwear, handheld selfie-vlog, cool overcast grade, deadpan tone, 9:16, captions on the lower third, always a single throwaway notification-joke caption. Start with an ai_generate_prompt step so later runs stay on theme without repeating this script.

Later:

Run Instagram Vlog with Captions again. Keep the theme. New joke, new walk.

That second message should not contain a new name. If the agent starts to say "Vlog Rerun v2", stop it. A full content pipeline is the same idea at a larger grain: one named recipe, many dated outputs. The brand kit can sit under the theme (colours, logo, caption style) so the name does not have to carry the hex codes.

Housekeeping that keeps reuse working

Before you spawn a "new" recipe, list what you already have. Equivalent work should reuse the name, not nearby synonyms. "Product Reel from Photo" and "Product Photo Reel" will never collapse into each other.

Keep run-specific data out of the name and in the inputs. Swap media_assets. Let ai_generate_prompt invent this week's line. Put the date in $runtime if you are on a schedule, not in the title.

Do not merge a step workflow into a scene workflow by recycling the scene workflow's name. The lookup will refuse the merge; you will either error or create a second row, depending on how the agent recovers. If you meant the scene recipe, say run_workflow.

Credits still apply per generation on every re-run. Reusing the name does not discount the work. Check the balance before a long chain; pricing is the tariff, and there is no free allowance sitting on the account.

FAQ

I already have "Vlog Rerun v2" in the list. Can I rename it onto the canonical name?

Yes, with edit_workflow on that workflow_id, changing name to the intent-based title. Do that before the next spawn, or the next spawn will miss it and insert yet another row. After the rename, spawn with the new task_name so reuse can hit.

What if I want two recipes that are almost the same?

Give them different names that still describe intent, not versions. "Instagram Vlog with Captions" and "TikTok Vlog with Captions" is a real fork (different format constraints). "Instagram Vlog with Captions" and "Instagram Vlog with Captions v2" is a naming accident.

Does run_workflow care about task_name?

No. run_workflow keys on workflow_id. task_name is the spawn path's way of finding that id without you passing it. Scene workflows should be re-run with run_workflow so freshness (new plot, same cast and style) stays on the path built for them.

Why was my re-run blocked?

The existing workflow has a real theme and a previous run, and the new steps still contained literal prompts or captions. That would have replayed last time's content. Prepend ai_generate_prompt that cites the saved theme, replace the literals with $step_0.generated.*, and spawn again with the same name. Identical replay requires a different task_name on purpose.