docs(start-sdk): document retiring a task's replay key

[MattDHill]

Why

A user updated StartOS, Knots, and DATUM Gateway and landed in an unrecoverable loop: two critical tasks on bitcoind's blocknotify, each demanding a different URL, each re-arming the moment the other was satisfied. DATUM was stopped the whole time, and no sequence of UI actions could settle it.

The cause is a documented-but-incomplete contract. createTask derives its replayId from [package-id]:[action-id], so when Knots renamed its config action other-config → autoconfig, DATUM's next release minted a new key rather than updating the old one. Nothing rewrites or reaps the abandoned key — it sat in the database still enforcing http://datum.startos:7152/NOTIFY from a pre-2.0 release, while the live key demanded the bridge address. The OS honors the legacy task shape (db/model/package.rs), so the orphan stayed fully functional.

The guide covered replayId idempotency but never the flip side, and tasks.md actively asserted the opposite:

You can safely re-run your init function on every container rebuild without accumulating stale tasks.

True only while the key itself is stable. That sentence is a fair part of why this went unnoticed.

An audit of the fleet found the same orphan in six other bitcoind dependents (lnd, fulcrum, mempool, public-pool, electrs, umbrel-bitcoin-ui). Those are currently harmless only because their demanded values happen to be unchanged — the next edit to any of those accept/set blocks reproduces this bug. A second class exists where the retired action was deleted rather than renamed; those are worse, because recheck_tasks can no longer resolve the action's input, the task's active flag freezes, and a frozen active: true + critical stops the package with no in-product remedy.

What changed

tasks.md

• Qualified the idempotency claim and linked it to the new section.
• Added Retiring a replay key: what changes the key, that clearing it belongs to the package that created the task, the migration pattern, and why neither StartOS nor the SDK can do it automatically — the OS can't distinguish a retired key from one not written this run, and the SDK can't reap "keys I didn't create this run" because tasks are legitimately raised from init, from actions, and by other packages.
• Documented both failure modes, the conditional-task case (citing fulcrum-bch-startos's NODE_TASK_KEYS + clearTask, which already solves this), and the start-cli package action clear-task … --force recovery path for boxes already stuck.

dependencies.md

• Expanded the one-line replayId note and cross-linked the new section, since that's where someone wiring up a cross-service task is actually reading.
• Fixed the severity union in the API signature: it read 'critical' | 'high' | 'medium' | 'low', but TaskSeverity is 'optional' | 'important' | 'critical'. Unrelated to the incident, corrected in passing.

Docs-only; no SDK surface change, so no version bump or changelog entry.

🤖 Generated with Claude Code