Start live widget development before the first edit

[SunkenInTime]

Summary

• Start weaver dev before the first widget source edit.
• Keep the live development session running as continuous authoring feedback.
• Clarify fallback behavior when the desktop host is unavailable.
• Use the running widget for live inspection and stop it when authoring is complete.

Testing

• Not run (documentation-only change).

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[greptile-apps]

Greptile Summary

This change makes weaver dev a continuous live-feedback surface during widget authoring and keeps deterministic capture as the fallback for platforms without a desktop host.

The revised workflow can leave the live widget on an older revision: it tells authors not to wait for a rebuild, then permits stopping weaver dev after authoring. A final save followed by an immediate stop cancels the pending rebuild and hot swap.

Overlapping rebuilds were verified to retain the latest revision. Development registry cleanup restores an installed widget when appropriate, and the reload client accepts only valid loopback TCP ports.

Merge safety: do not merge until the final-edit deployment gap is addressed in the workflow guidance or in weaver dev shutdown behavior.

Confidence Score: 4/5

The workflow is not safe to merge as written because it can report a stale live widget after the final source edit.

The final-save failure was reproduced through an executed ordering assertion against the production debounce and shutdown path, with focused reload integration coverage also passing. Focused execution verified overlapping rebuild retention, reload-port validation, and portable regression coverage. Native desktop rendering could not be observed because the available Linux environment does not support Weaver's desktop host.

Files Needing Attention: skills/conjure-widget/SKILL.md needs final-rebuild guidance. Alternatively, cli/src/index.ts can make shutdown drain and await pending rebuild work before unregistering the development widget.

T-Rex Logs

What T-Rex did

• T-Rex produced proof for a posted P1 finding.
• The narrow CLI test suite passed with 19 tests and no failures.
• T-Rex ran the requested verification, but its local artifact references were not uploaded.
• Exact code evidence shows the watcher detects overlapping invocations and schedules a rebuild, ensuring the later edit is rebuilt.
• Before-and-after port validation checks show malformed values rejected, valid loopback accepted, and the DEV_RELOAD_DIFF remains unchanged, with the exact test and host results captured.

_{Ran code and verified through T-Rex}

Comments Outside Diff (1)

1. General comment

   Final edit can be dropped when users stop weaver dev during debounce

   • Bug
     • The PR instructs users to continue editing without waiting for presentation, then permits stopping the process when authoring is complete. If the final save is followed immediately by SIGINT or SIGTERM, the CLI cancels the 100 ms deferred rebuild. The live widget never receives that saved revision’s in-place reload and remains stale until it is stopped/restarted or a later dev session rebuilds it.
   • Cause
     • The watcher schedules the only rebuild/hot-swap path through setTimeout(..., 100) at cli/src/index.ts:993-1000, while the shutdown handler unconditionally runs clearTimeout(debounce) at cli/src/index.ts:1025-1032. Shutdown does not drain the queued debounce or await rebuild() before removing the dev registry entry and signaling host reconciliation at cli/src/index.ts:1036-1051.
   • Fix
     • Before documenting non-waiting edits as a complete safe workflow, either (1) change weaver dev shutdown to flush/await a pending debounce and any in-flight rebuild before unregistering, with clear failure reporting, or (2) explicitly require waiting for weaver dev bundle ready for in-place hot swap (or manifest restart confirmation) after the final edit before stopping the session. The former preserves the intended documentation workflow.

   _{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "Start live widget development before the..." | Re-trigger Greptile}

[greptile-apps]

Final edit can be dropped before hot swap

The workflow tells authors not to wait for presentation between edits and permits stopping weaver dev after authoring. A final save followed by shutdown within the watcher's 100 ms debounce is canceled before bundleWidget and signalDevReload run, leaving the desktop widget on its prior revision. Require the final successful rebuild or hot-swap message before live inspection, reporting, or stopping the session, or make shutdown flush and await pending work.

_{Ran code and verified through T-Rex}