Desktop: heartbeat creation has an undocumented destination/targetThreadId requirement

Summary

The model-facing codex_app.automation_update contract leaves a conditional requirement unstated: heartbeat creation needs an explicit targetThreadId or destination: "thread", although both fields are advertised as optional and the description presents heartbeats as attached to the current task.

This is a small schema/documentation mismatch, not a claim that heartbeat creation is generally broken.

Environment

• Windows, Codex Desktop; observed September 11, 2026.
• Source session metadata records CLI version 0.153.4.
• The exact Desktop package build was not captured in this occurrence's evidence.

Observed sequence

1. In an existing local task, the agent invoked automation_update with mode: "create" and kind: "heartbeat", omitting both destination and targetThreadId.
2. The tool rejected creation with:
   Missing targetThreadId or destination=thread
3. The first call was an explicit validation failure; no automation was created.
4. Creation succeeded after explicitly supplying destination: "thread". No duplicate automation was created.

The heartbeat branch exposed to the agent marks destination? and targetThreadId? optional without stating that one is required for create. The same omission remains in the tool description available to this reporting task; no new automation was created merely to reproduce the error.

Expected

Either default an omitted target to the calling local task, or explicitly document and encode the conditional requirement in the model-facing create schema: supply a targetThreadId OR destination="thread".

Impact and workaround

One avoidable failed tool call and a corrective creation call. Use destination: "thread" for a heartbeat attached to the current task. No data loss or scheduler failure was observed.

Related: #35601 concerns a different schema problem in which the heartbeat branch is absent entirely; here heartbeat is exposed and works once the unstated target requirement is satisfied.

No automation prompt, task IDs, account data, credentials, or raw logs are included.

Start by locating the model-facing codex_app.automation_update contract and its heartbeat create schema or tool description. Check how destination and targetThreadId are described and validated; done means the conditional requirement is explicit and consistent, with the existing destination="thread" workaround covered.