Refine Hub
Refine 4.3.2
Runbooks

Update Refine from Source

Outcome: a running Refine source checkout advances to its latest configured upstream commit only after the candidate builds, then restarts and reports healthy. Published-release updates remain unchanged.

Preconditions

  • The invoked bin/refine belongs to the same source checkout being inspected.
  • The controller checkout is on a branch with a reachable configured remote.
  • The fetched commit is a fast-forward descendant of the current commit.
  • The installed update Agent can pause new workflow admission and observe or safely reconcile preserved active work on the selected port.

Uncommitted staged, unstaged, or untracked changes are not a blocker for the web source-promotion workflow: queueing an update preserves them automatically in a named git stash (refine-update-<timestamp>), reports the stash reference in the operation record and UI, and never reapplies the stash itself. The stash is created only after a real fast-forward update is confirmed, so a checkout with nothing to do is never touched. Local commits that diverge from the upstream still block promotion. The granular system source-promote path stays strict and performs no stashing at all.

This workflow is unavailable for a gitless published product home. Use the published-release update workflow there; do not add Git metadata or infer a source checkout from the caller’s working directory.

UI Workflow

When the running Refine checkout is discoverable, the source-update control in the main navigation provides the same operation regardless of the attached target app. Cached reads never run Git fetch. Automatic refresh runs at most once per hour by default; duplicate manual clicks and clients share one supervised fetch.

  1. Open Controls and use the source-update action to check the configured upstream.
  2. Resolve any reported blocker without overwriting work, then check again.
  3. Select Update Refine once to queue the installed maintenance Agent. A failed or interrupted operation permits a manual retry.
  4. Keep the page open or return later; the source control reconnects through restart. Detailed source and operation evidence remains available through refine system source-status and the shared source API.
  5. Require the final message Latest source promoted and Refine is healthy.

CLI Parity

Run the launcher’s deterministic local update. It fetches the configured upstream first. When that upstream has no new commits, it exits without stopping Refine, stashing work, rebuilding, or restarting. Otherwise, it stops the default daemon, runs git stash and git pull, rebuilds, and starts the default daemon:

./r system update

This launcher command is intentionally separate from the restart-safe UI workflow and accepts no arguments. ./r system service-install and ./r system service-uninstall only register or remove the port-scoped systemd or launchd service; they never fetch, pull, or otherwise update Refine source.

Inspect without fetching:

./r system source-status --port 8082 --runtime-root run

Fetch and re-evaluate availability:

./r system source-status --fetch --port 8082 --runtime-root run

Queue the same external handoff used by the UI:

./r system source-promote --port 8082 --runtime-root run

The command returns the durable operation id before the daemon stops. The revisioned record under <runtime-root>/<port>/operations/ is authoritative; source-promotion.json is a redacted projection repaired from it after a crash. run/<port>/... is only the checkout-local default.

More precisely, run resolves only to the owning checkout’s canonical <checkout>/run; arbitrary relative or external absolute runtime roots are rejected before a check, build, helper launch, or source mutation.

Restart-Safe Handoff Evidence

The operation reserves a unique attempt and nonce verifier before submission. Reservation or restart_safe_handoff_preparing is not proof that a helper is live. The helper receives the operation id, attempt id, and raw nonce, then atomically claims before delay or mutation. The registry records the expected systemd unit, launchd label, or detached process fingerprint and a bounded claim deadline, followed by a structured receipt. Only receipt or claim plus exact live identity can activate restart_safe_handoff.

The candidate is built in isolated storage and then atomically installed at the stable <checkout>/bin/refine path. Service registration continues to point at that path across the restart. The exact prior binary is backed up for this attempt and restored together with prior source state if activation or health verification fails; the existing attempt/receipt protocol remains the authority for helper liveness.

After a daemon restart, Refine adopts one exact live claimant. No claimant, identity mismatch, stale or late claim, or ambiguous evidence settles visibly as interrupted or failed and retryable; it never remains running because of a stage string. A retry receives a new attempt only after the old attempt is terminal. Public API, SSE, browser, CLI, and MCP output include only the nonce verifier and redacted receipt, never the raw nonce.

Failure And Recovery

  • build_candidate: the daemon and checkout were not changed. Fix the build failure and check again.
  • verify_idle: work or source state changed while the candidate built. The daemon and checkout were not changed; restore quiescence and check again.
  • stop_daemon: the checkout was not advanced. Inspect the port-scoped daemon process records and retry only after the runtime is idle.
  • activate_source: the helper restarts the previous daemon when possible; inspect the reported Git precondition failure.
  • restart_daemon: the helper attempts to restore the prior commit and restart the previous daemon. Follow the persisted recovery text and verify with:
  • restart_safe_handoff_preparing: inspect the operation attempt. Before the claim deadline, a manager job may still claim. After the deadline, zero or ambiguous claimants must settle interrupted or failed before retry.
  • cancelling: cancellation has fenced late receipts and claims but is still observing or terminating the exact helper, restoring registration/source as required, and restoring the recorded workflow-admission intent. Do not call it cancelled until the operation becomes terminal.
./r system status --port 8082 --runtime-root run
./r system source-status --port 8082 --runtime-root run

Never claim success from a branch change alone; daemon health verification is part of the operation. Final evidence must include the healthy daemon, the live executable identity, and source status at the promoted commit; if rollback was required, report the restored commit and executable instead.