devflow execution handoff <domain> is a read-only operational projection of the
current computed lifecycle action, current Git state, the most recent matching
checkpoint, and unfinished DevFlow CLI mutations. It is not a substitute for
devflow status, WORK evidence, audits, or the hosted/standalone lease guards.
The runtime automatically records start/finish events for lifecycle-mutating DevFlow CLI invocations across planning, WORK, audits, decisions, delivery and finalization. This records command exit codes, not proof of the result. A missing finish event means unknown, not failure, success, or permission to replay. Commands that only inspect state do not create journal events. Direct source edits, model reasoning, and external test commands are not automatically observed.
After a material milestone in any long-running role (planning, implementation, audit, verification, or finalization), record a concise caller-reported checkpoint when safe. Do not checkpoint every tool call or invent results:
devflow execution checkpoint <domain> --stage implementation \
--note 'Service change made; regression pending' \
--completed 'Service method updated' \
--pending 'Run the controller integration test' \
--verification './gradlew test -> not yet run' --host codex
Optionally attach a structured Execution Receipt to the same checkpoint:
devflow execution checkpoint <domain> --stage implementation --note 'Service updated' \
--decision 'Reuse existing period validator' \
--assumption 'Policy question remains open' \
--constraint 'Keep API contract unchanged' \
--file 'apps/hr/src/WorkStandardService.java' \
--next-step 'Run controller regression' --host codex
Receipt fields are short, optional, caller-reported hints. --file accepts only
repository-relative paths; do not store source bodies, secrets, personal data, or
unapproved policy decisions. Receipts stay in the existing checkpoint event and
have no independent lifecycle or approval authority. Existing checkpoints remain
readable without migration.
For a low-token supervisor restart, inspect the bounded JSON first:
devflow execution resume-brief <domain>
The 4KB output keeps the computed next action, current WORK/Git pointers,
pending-child and owner-check flags, unconfirmed-command count, and recent
checkpoint hints. The brief is advisory only and cannot grant a lease,
resolve a pending child, verify a test, or mark WORK complete. Use the full
execution handoff when safety is ambiguous or more context is necessary.
Use a stage appropriate to the actual lifecycle action (planning, implementation, verification, audit, finalization, etc.). Never claim a verification result that was not observed. Do not copy full conversations, source bodies, private tokens, credentials, or raw test logs into a checkpoint. Prefer references to existing WORK/PLAN/DECISIONS/audit evidence and Git paths. No new mandatory checkpoint or lifecycle artifact is introduced, and this facility requires no additional model call. If a journal write fails, continue the ordinary lifecycle and report the missing observation.
At a new hosted /goal entry, inspect devflow execution handoff <domain> before
claiming a session. Its orchestration.hosted.host, owner_marker, and
requires_termination_verification guide the operator; they are not ownership
credentials. If an idle older host retains a live lease, only a human who has
independently confirmed the source host stopped may run session-handoff per
core/protocol/host-telemetry.md. A pending or unknown child cannot be handed
off; use the pre-existing administrator recovery procedure after termination.
Hosted primary steps additionally retain a bounded dispatch anchor inside the
existing guarded reservation: original action, selected WORK ID, WORK status and
commit evidence fields at reservation, plus HEAD. This is a historical pointer,
not live WORK state or proof that a child completed. orchestration.hosted
projects pending_primary and last_primary without exposing session/step IDs.
A completed child outcome means the native child was acknowledged, not that
work done, acceptance verification, or an audit happened. On handoff, always
re-read the referenced WORK from the repository; if it is still in_progress,
continue that WORK and verify actual source changes before editing. Existing
pre-anchor records yield null for these pointers and keep existing fencing.
On another host, run devflow execution handoff <domain> once when recovery
context is needed. Use devflow status to select the actual next action, verify
source changes and test outcomes, and inspect original cited files on demand.
An action-specific checkpoint from a former HEAD or worktree is advisory;
its freshness flags never imply its observations are correct. A completed claim
in a checkpoint does not mark WORK done or bypass verification/audit gates.
All journal rows are local under .devflow/runtime/<domain>/execution-journal.sqlite3.
They never copy STATE/WORK as another source of lifecycle authority; action
identities are only correlation hints. Corrupt records fail clearly rather than
silently authorizing progress. This journal does not reclaim pending native
children, steal leases, infer provider rate limits or automatically switch CLIs.
The existing host-telemetry.md recovery requirements still apply.