DSH plugin goals: revision refs, phases, and activation
A goal's "state" lives on two layers: one in the log, one in the process. DSH plugin's persistent phase answers what happened to the goal, while activation only answers whether a continuation consumer may start another Round right now. Collapse the two and you get "the goal survived the restart but auto-continuation vanished."
GoalRef is a compare-and-set revision
Every accepted persistent change increments the revision.(source)
GoalId is a branded id. Callers modify one exact revision through GoalRef, which has just two fields: a stable id and a positive integer revision.
That gives concurrent updates a deterministic winner: a stale revision is rejected rather than quietly overwriting someone else's edit. When "my goal change did nothing," first check whether the revision in hand has already expired.
The persistent phase answers what happened to the goal; process-local activation separately answers whether a continuation consumer may start another Round. The split is deliberate.
Four persistent phases
blocked is the only state meaning "stopped because of a problem."(source)
GoalPhase has four values:
active— the goal is underway;paused— paused;blocked— stopped because of a problem, and it must carry a reason;complete— finished.
GoalBlockReason has two parts: a policy-chosen stable code (lower-kebab-case, used for routing) and a non-empty message for humans and the model.
GoalSnapshot adds objective, phase, optional blockedReason, and maxGoalRounds to GoalRef. blockedReason exists exactly when phase is blocked — that invariant is how you judge whether a state is legal.
What in GoalView is derived
activation never persists.(source)
GoalView adds four fields to the snapshot: roundsStarted (the highest round admitted for this goal), createdAt, updatedAt, and activation.
The first three come from persistent events and projection; activation is process-local continuation eligibility and never persists. The service also publishes process-local activation edges without changing persistent state, and clients consume that event for live status.
GoalActivationChanged carries sessionId plus an optional current goal (id, revision, activation); the field is absent when no goal exists.
One event for every persistent change
Either a complete snapshot or a clear tombstone.(source)
Every change is a persistent goal/change session event with one of two payloads:
GoalSnapshotChangeMeta—kind,version: 1,operation(excludingclear), the completegoalsnapshot,roundsStarted,createdAt, andupdatedAt;GoalClearChangeMeta—kind,version: 1,operation: 'clear',cleared: GoalRef, andclearedAt.
Strict folding and the persistent projection derive lifecycle state only from these events; inbox changes never affect goal state. That boundary keeps "the user queued a new message" and "the goal phase changed" from interfering.
Round numbers are stamped by the continuation consumer
roundsStarted advances only through admitted user messages.(source)
The continuation consumer stamps a positive, consecutive Round number and the current revision onto each admitted user message round. Only those admitted user/message events advance roundsStarted.
Replay rejects five kinds of illegal input: a non-positive Round, a numbering gap, a stale revision, an already stopped phase, and exceeding the cap. GoalMessageSource is the shape of that attribution: kind: 'goal', goalId, revision, and a positive round.
So "which round is the goal on" is read from the Round on the message, not by counting messages. That is exactly why replay can validate strictly.
Requests, notifications, and service behavior
Create resolves defaults; edit supplies at least one field.(source)
CreateGoalRequest has only objective and optional maxGoalRounds. Creation distinguishes "caller omitted the field" from "use the deployment configured value," and create() resolves the latter internally.
EditGoalRequest is a partial replacement, and the runtime validator requires at least one field. Every change notification carries the accepted operation and the exact revision; a clear operation carries no goal. GoalChanged is shaped as { operation, ref, goal? }.
Worth memorizing, the GoalService duties: resolve create defaults, read strict replay results from the optionally registered goal projection, verify the passed agent is the exact live instance in the registry, perform compare-and-set changes, and emit goal/changed notifications with listener faults isolated.
When the registry or key is missing, the first access that depends on them fails. That deferred failure is subtler than a load-time failure, so watch when the first access actually happens.
disarm(agent) changes neither the persistent phase nor the revision; it only removes process-local continuation authorization. The lifecycle owner calls it before unloading the driver, and a later human-authorized resume records a fresh activation edge.
Verification: create, update, restart, complete
Watch the revision, the persistent phase, and activation together.(source)
- Call
createwithoutmaxGoalRoundsand assert the deployment value was used withrevision1. - Call
editwith a staleGoalRefand assert rejection with the goal untouched. - Call
pausethenresumeand assert the phase changed, the revision incremented, and activation updated via the event. - Restart the process, call
get, and assert phase androundsStartedmatch the pre-restart values. - Call
blockwith a lower-kebab-case code and assertblockedReasonexists; then callcompleteand assert it disappears. - Call
clearand assert the returned tombstone revision is one higher than the cleared snapshot and history remains replayable.
If step 4 loses activation while the phase survives, that is expected: activation was always process-local.
For goals that keep failing, see goal and autonomous loop fixes; for persistence boundaries, see the persistence seam.
One line to close: revisions drive compare-and-set, blocked is the only problem-stop, activation never lands on disk, every change is one event, Rounds are stamped by the continuation consumer, and disarm removes authorization without touching the phase.
FAQ
No. DSH plugin states activation is only process-local continuation eligibility. DSH plugin's persistent phase answers what happened to the goal; activation answers whether a continuation consumer may start another Round.
DSH plugin uses blocked for stopping because of a problem, the only such persistent state. DSH plugin also requires a policy-owned code and explanation, while paused is simply paused.
Yes. DSH plugin edits through GoalRef compare-and-set. DSH plugin increments the revision on every accepted persistent change, and stale revisions are rejected during replay.
No. DSH plugin clear keeps a tombstone and the history. DSH plugin writes a goal/change event with operation clear carrying cleared and clearedAt.
Related Terms
- GoalRef
- GoalRef is the compare-and-set identity of one exact goal revision: a stable GoalId plus a positive integer revision.— packages/goal/goal/src/types.ts
- GoalPhase
- GoalPhase is the persistent continuation phase: active, paused, blocked, or complete.— packages/goal/goal/src/types.ts
- GoalSnapshot
- GoalSnapshot is the complete persistent state written by every non-clear change: goal, phase, optional block reason, and round cap.— packages/goal/goal/src/types.ts
- GoalMessageSource
- GoalMessageSource is the attribution on an accepted continuation round: goalId, revision, and a positive round number.— packages/goal/goal/src/types.ts
Sources
- DeepSeek Harness reference - Session goals· deepseek-ai
- packages/goal/goal/src/types.ts· deepseek-ai