supervisor

package
v0.3.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 8, 2026 License: MIT Imports: 17 Imported by: 0

README

package supervisor

Purpose

supervisor owns post-admission run/attempt operational truth: claim leases, track authenticated progress, enforce stalls, finalize verified results, cancel/cleanup, and reconcile after daemon restart — all via CAS on durable routedrun state.

Key Types

Type Role
Supervisor Lifecycle authority
SupervisorOption WithAuditLogger, WithTimer, …
DurableStore CAS subset of routedrun store APIs
ResultStore Terminal result persistence
ControlJournalFactory / ControlJournalHandle Terminal-event fence
ProgressEvent / ResultEvent / CheckpointEvent Authenticated worker events
ClaimOptions Attempt claim parameters
GovernedOperationKind model / HTTP / MCP in-flight ops
ReferenceWorker / ReferenceWorkerConfig Deterministic conformance worker
attemptTracker Per-attempt liveness/stall bookkeeping (unexported)

Key Functions

Symbol Role
NewSupervisor Construct supervisor over stores/journal
ClaimForRun Create/claim attempt + lease
TrackProgress Accept HMAC-verified progress
HandleCheckpoint / HandleResult Checkpoint and terminal result
HandleModelStart/End, HandleHTTP*, HandleMCP* Governed op brackets
CheckStall Stall evaluation
Cancel / Finalize / Cleanup Terminal paths
Reconcile Restart-safe recovery
UnauthenticatedActivity Explicitly rejected non-auth activity
ReferenceWorker.Run Multi-phase signed event simulation

Architecture

AdmitInvocation (routedrun)
        |
        v
Supervisor.ClaimForRun --> Attempt + Lease + control key
        |
        +-- worker progress (HMAC) --> TrackProgress
        +-- governed ops --> stall deadline extension
        +-- checkpoint --> SaveCheckpoint
        +-- verified result --> CAS terminal + ResultStore
        v
Cleanup (revoke lease, release resources)

Daemon restart --> Supervisor.Reconcile

Sentinel errors (ErrLeaseMismatch, ErrInvalidHMAC, ErrNotVerifiedResult, …) are stable for errors.Is matching.

Usage

sup := supervisor.NewSupervisor(durable, results, journals, opts...)
attemptID, err := sup.ClaimForRun(ctx, runID, invocationID)
if err != nil {
    return err
}
if err := sup.TrackProgress(ctx, attemptID, progressEvent); err != nil {
    return err
}
return sup.HandleResult(ctx, attemptID, resultEvent)

Documentation

Overview

Package supervisor implements the durable, request-context-independent lifecycle supervisor for long-running invoke jobs.

The Supervisor is the operational-truth authority for a run after durable admission. It drives every state transition through compare-and-swap (CAS) writes on the durable store, never mutating state without a generation check. It runs as a daemon-level component invoked after admission and re-invoked on restart for reconciliation — independent of any CLI/gRPC request context.

Liveness model

Accepted authenticated activity includes progress/heartbeat with a valid HMAC, model/HTTP/MCP start/end, checkpoint/artifact commit, and the terminal job-result event. Stdout/stderr spam, mere process existence, and unauthenticated file writes do NOT count as progress.

Stall model

A stall timer per attempt fires when (now - lastActivity) exceeds the stall timeout AND no in-flight governed operation is active. While a governed operation (model/HTTP/MCP) is in flight, the stall deadline is bounded by the operation deadline (min of operation timeout, attempt-lease remaining, and active-time remaining), not the raw stall timeout alone.

Finalization model

Success is finalized ONLY from a verified InvokeJobResult event for the active lease. A container exiting zero is NOT sufficient. Finalization, cancellation, and cleanup are idempotent under races via CAS generations and a terminal-event fence (the control journal).

Restart reconciliation

On reconcile, the supervisor revokes ambiguous active leases (no committed terminal event) and marks FAILED with reason daemon_restart; ingests any already-committed terminal result/checkpoint without blindly re-invoking work; preserves safe checkpoint/artifact state; closes interrupted active-time segments exactly once; and never accrues time while the durable workflow is fully PAUSED or NEEDS_REPLAN.

ReferenceWorker provides a deterministic multi-phase test worker that emits signed progress/checkpoint/result events for conformance tests.

Package supervisor implements the durable, request-context-independent lifecycle supervisor for long-running invoke jobs (B30-T05).

The Supervisor is the operational-truth authority for a run after durable admission (B26 state + B27 authenticated progress). It drives every state transition through compare-and-swap (CAS) writes on the durable store, never mutating state without a generation check. It is independent of any CLI / gRPC request context: it runs as a daemon-level component that the daemon invokes after admission and that the daemon re-invokes on restart for reconciliation.

Liveness model (b30-summary.md T05):

  • Accepted authenticated activity: progress/heartbeat with a valid HMAC, model/HTTP/MCP start/end, checkpoint/artifact commit, and the terminal job-result event.
  • NOT accepted as progress: stdout/stderr spam, process existence, or unauthenticated file writes.

Stall model:

  • A stall timer per attempt fires when (now - lastActivity) exceeds the stall timeout AND no in-flight governed operation is active.
  • While a governed operation (model/HTTP/MCP) is in flight, the stall deadline is bounded by the operation deadline (the min of the operation timeout, attempt-lease remaining, and active-time remaining), not the raw stall timeout.

Finalization model:

  • Success is finalized ONLY from a verified InvokeJobResult event for the active lease. A container exiting zero is NOT sufficient.
  • Finalization, cancellation, and cleanup are idempotent under races via CAS generations and a terminal-event fence (the control journal).

Restart reconciliation (b30-summary.md T05 reconcile):

  • Revoke any ambiguous active lease (an active lease with no committed terminal event), mark FAILED with reason "daemon_restart".
  • Ingest any already-committed terminal result/checkpoint; never blindly re-invoke work.
  • Preserve safe checkpoint/artifact state for B39 continuation.
  • Conservatively close an interrupted active-time segment exactly once; never double-charge or forgive active time.
  • Never accrue time while the durable workflow is fully PAUSED or NEEDS_REPLAN; never leave a frozen workflow with an active lease, capability, or active/in-flight reservation.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrAttemptNotFound is returned when the supervisor has no record of the
	// attempt (it was never claimed or has been cleaned up).
	ErrAttemptNotFound = errors.New("supervisor: attempt not found")
	// ErrLeaseMismatch is returned when an event references a lease that is not
	// the active lease for the attempt (a late or forged event).
	ErrLeaseMismatch = errors.New("supervisor: lease mismatch")
	// ErrInvalidHMAC is returned when a progress or result event carries an
	// HMAC that does not verify against the attempt's control key.
	ErrInvalidHMAC = errors.New("supervisor: invalid HMAC")
	// ErrAlreadyTerminal is returned when a terminal transition is requested on
	// an attempt that is already in a terminal state. It is NOT an error for
	// idempotent finalization: Finalize/Cancel return nil when the existing
	// terminal state matches the request.
	ErrAlreadyTerminal = errors.New("supervisor: attempt already terminal")
	// ErrNotVerifiedResult is returned when a success finalization is requested
	// without a verified InvokeJobResult event for the active lease.
	ErrNotVerifiedResult = errors.New("supervisor: success requires verified result event")
	// ErrInvalidArgument is returned for malformed supervisor inputs.
	ErrInvalidArgument = errors.New("supervisor: invalid argument")
	// ErrDigestMismatch is returned when a ResultEvent's ResultDigest does not
	// match the SHA-256 of its StructuredResult.
	ErrDigestMismatch = errors.New("supervisor: result digest mismatch")
	// ErrContextBoundExceeded is returned when a durable worker exceeds its
	// configured context bound (F27).
	ErrContextBoundExceeded = errors.New("supervisor: context bound exceeded")
)

Sentinel errors. Callers MUST NOT infer behavior from error strings; match with errors.Is.

Functions

This section is empty.

Types

type AuditLogger 

type AuditLogger interface {
	Append(record audit.AuditRecord) error
}

AuditLogger publishes audit/timeline events. The supervisor publishes ONLY AFTER the durable state commit (CAS success) succeeds, never before.

type CheckpointEvent 

type CheckpointEvent struct {
	AttemptID  routedrun.AttemptID
	LeaseID    routedrun.LeaseID
	Checkpoint *routedrun.SemanticCheckpoint
	HMAC       string
}

CheckpointEvent is an authenticated checkpoint/artifact commit. Committing a checkpoint counts as accepted activity (it is durable forward progress).

type ClaimOptions 

type ClaimOptions struct {
	// StallTimeoutMs is the per-attempt stall timeout. If 0, defaults to
	// routedrun.DefaultStallTimeoutMs.
	StallTimeoutMs int64
	// ModelCallTimeoutMs is the per-attempt model-call timeout (operation
	// deadline ceiling). If 0, defaults to routedrun.DefaultModelCallTimeoutMs.
	ModelCallTimeoutMs int64
	// AttemptLeaseMs is the attempt lease duration. If 0 the attempt has no
	// lease (stall/active-time still apply).
	AttemptLeaseMs int64
}

ClaimOptions configures a Claim.

type ControlJournalFactory 

type ControlJournalFactory interface {
	// OpenControlJournal returns a control journal for the given run/attempt.
	// The returned journal must be closed by the caller.
	OpenControlJournal(runID routedrun.RunID, attemptID routedrun.AttemptID) (ControlJournalHandle, error)
}

ControlJournalFactory opens (or creates) the per-attempt control journal. The supervisor uses the journal to append ACCEPTED / STARTED / PROGRESS_REF / SUCCEEDED / FAILED / CANCELLED events and to replay them on restart.

type ControlJournalHandle 

type ControlJournalHandle interface {
	Append(event routedrun.InvokeJobEvent) error
	Read(fromSeq int64) ([]routedrun.InvokeJobEvent, error)
	Close() error
}

ControlJournalHandle is the per-attempt control journal interface the supervisor uses. It mirrors routedrun.ControlJournal's Append/Read/Close.

type DurableStore 

type DurableStore interface {
	// Run lifecycle.
	GetRun(ctx context.Context, runID routedrun.RunID) (*routedrun.RunRecord, error)
	GetRunGeneration(ctx context.Context, runID routedrun.RunID) (int64, error)
	UpdateRun(ctx context.Context, run *routedrun.RunRecord, expectedGeneration int64) error

	// Attempt lifecycle.
	CreateAttempt(ctx context.Context, attempt *routedrun.AttemptRecord) error
	GetAttempt(ctx context.Context, attemptID routedrun.AttemptID) (*routedrun.AttemptRecord, error)
	GetAttemptGeneration(ctx context.Context, attemptID routedrun.AttemptID) (int64, error)
	UpdateAttempt(ctx context.Context, attempt *routedrun.AttemptRecord, expectedGeneration int64) error
	ListAttempts(ctx context.Context, runID routedrun.RunID) ([]*routedrun.AttemptRecord, error)

	// Workflow lifecycle (for active-time accounting).
	GetWorkflow(ctx context.Context, workflowID routedrun.WorkflowID) (*routedrun.WorkflowRecord, error)
	UpdateWorkflow(ctx context.Context, wf *routedrun.WorkflowRecord, expectedGeneration int64) error

	// Active-time ledger.
	GetActiveTimeLedger(ctx context.Context, workflowID routedrun.WorkflowID) (*routedrun.ActiveTimeLedger, error)
	GetActiveTimeLedgerGeneration(ctx context.Context, workflowID routedrun.WorkflowID) (int64, error)
	PutActiveTimeLedger(ctx context.Context, workflowID routedrun.WorkflowID, ledger *routedrun.ActiveTimeLedger, expectedGeneration int64) error

	// Checkpoints (preserved on restart).
	SaveCheckpoint(ctx context.Context, cp *routedrun.SemanticCheckpoint) error
	GetLatestCheckpoint(ctx context.Context, attemptID routedrun.AttemptID) (*routedrun.SemanticCheckpoint, error)
}

DurableStore is the subset of routedrun.LocalStore the supervisor drives state transitions through. Every mutating method uses compare-and-swap on a generation; the supervisor NEVER mutates durable state without a CAS.

type GovernedOperationKind 

type GovernedOperationKind int

GovernedOperationKind enumerates the in-flight governed operations whose presence exempts an attempt from the stall timer (bounded by the operation deadline). These are the authenticated model / HTTP / MCP operations whose start/end the supervisor tracks. 

const (
	GovernedOpUnspecified GovernedOperationKind = iota
	GovernedOpModel
	GovernedOpHTTP
	GovernedOpMCP
)

type ProgressEvent 

type ProgressEvent struct {
	// AttemptID is the attempt this progress pertains to.
	AttemptID routedrun.AttemptID
	// LeaseID is the active lease for the attempt. Must match the supervisor's
	// recorded active lease or the event is rejected (late/forged).
	LeaseID routedrun.LeaseID
	// Sequence is the monotonic progress sequence. Must be strictly greater
	// than the last accepted sequence (no replay, no gaps).
	Sequence int64
	// Timestamp is the event timestamp (wall).
	Timestamp time.Time
	// Phase is an opaque phase label from the worker.
	Phase string
	// HMAC is the hex-encoded HMAC-SHA256 over the canonical event fields,
	// keyed by the attempt's control key. Empty or invalid => rejected.
	HMAC string
}

ProgressEvent is an authenticated progress / heartbeat event. The supervisor accepts it as liveness evidence ONLY when HMAC verifies against the attempt's control key. An empty HMAC or a mismatched HMAC is rejected (TestForgedProgressRejected).

type ReferenceWorker 

type ReferenceWorker struct {
	// contains filtered or unexported fields
}

ReferenceWorker is a deterministic simulation of a durable multi-turn agent that exercises the supervisor's lifecycle APIs exactly as a real durable worker would. No LLM is called; no network is used.

func NewReferenceWorker 

func NewReferenceWorker(cfg ReferenceWorkerConfig) *ReferenceWorker

NewReferenceWorker creates a new ReferenceWorker with the given config.

func (*ReferenceWorker) ArtifactRefForPhase 

func (w *ReferenceWorker) ArtifactRefForPhase(phase int) string

ArtifactRefForPhase returns the artifact reference for the given phase.

func (*ReferenceWorker) CheckpointDigestForPhase 

func (w *ReferenceWorker) CheckpointDigestForPhase(phase int) string

CheckpointDigestForPhase returns the checkpoint digest for the given phase (1-indexed).

func (*ReferenceWorker) CheckpointDigests 

func (w *ReferenceWorker) CheckpointDigests() []string

CheckpointDigests returns all checkpoint digests accumulated during the run.

func (*ReferenceWorker) CompletedTurns 

func (w *ReferenceWorker) CompletedTurns() []int

CompletedTurns returns the list of completed turn numbers.

func (*ReferenceWorker) ContextBound 

func (w *ReferenceWorker) ContextBound() int

ContextBound returns the configured context bound.

func (*ReferenceWorker) CurrentCheckpointID 

func (w *ReferenceWorker) CurrentCheckpointID() string

CurrentCheckpointID returns the latest checkpoint ID.

func (*ReferenceWorker) FinalResultDigest 

func (w *ReferenceWorker) FinalResultDigest() string

FinalResultDigest returns the final result digest.

func (*ReferenceWorker) FinalResultResult 

func (w *ReferenceWorker) FinalResultResult() string

FinalResultResult returns the final structured result JSON.

func (*ReferenceWorker) GetInvocationID 

func (w *ReferenceWorker) GetInvocationID() routedrun.InvocationID

GetInvocationID returns the invocation ID used by this worker (F28).

func (*ReferenceWorker) GetRunID 

func (w *ReferenceWorker) GetRunID() routedrun.RunID

RunID returns the run ID used by this worker (F28).

func (*ReferenceWorker) GetWorkflowID 

func (w *ReferenceWorker) GetWorkflowID() routedrun.WorkflowID

GetWorkflowID returns the workflow ID used by this worker (F28).

func (*ReferenceWorker) MaxAccumulatedTokens 

func (w *ReferenceWorker) MaxAccumulatedTokens() int

MaxAccumulatedTokens returns the peak accumulated token count during the run.

func (*ReferenceWorker) ProgressSequences 

func (w *ReferenceWorker) ProgressSequences() []int64

ProgressSequences returns all progress event sequences emitted.

func (*ReferenceWorker) PromptForTurn 

func (w *ReferenceWorker) PromptForTurn(turn int) string

PromptForTurn returns the model prompt sent at the given turn (1-indexed).

func (*ReferenceWorker) Run 

func (w *ReferenceWorker) Run(ctx context.Context, opts RunOptions) error

Run executes the deterministic research dossier.

func (*ReferenceWorker) TurnCount 

func (w *ReferenceWorker) TurnCount() int

TurnCount returns the total number of turns executed.

type ReferenceWorkerConfig 

type ReferenceWorkerConfig struct {
	Supervisor   *Supervisor
	AttemptID    routedrun.AttemptID
	LeaseID      routedrun.LeaseID
	ControlKey   []byte
	ArtifactRoot string

	// RunID is the run this worker belongs to (F28).
	// If empty, defaults to "run-ref-worker".
	RunID routedrun.RunID
	// WorkflowID is the workflow this worker belongs to (F28).
	// If empty, defaults to "wf-ref-worker".
	WorkflowID routedrun.WorkflowID
	// InvocationID is the invocation this worker serves (F28).
	// If empty, defaults to "inv-ref-worker".
	InvocationID routedrun.InvocationID

	// ContextBound is the maximum accumulated context in bytes (F27).
	// If zero, defaults to 65536 (64KB).
	ContextBound int
}

ReferenceWorkerConfig holds the dependencies for a ReferenceWorker run.

type ResultEvent 

type ResultEvent struct {
	// AttemptID is the attempt this result pertains to.
	AttemptID routedrun.AttemptID
	// LeaseID is the active lease for the attempt. Must match.
	LeaseID routedrun.LeaseID
	// RunID is the run this result finalizes.
	RunID routedrun.RunID
	// WorkflowID is the workflow this result finalizes.
	WorkflowID routedrun.WorkflowID
	// InvocationID is the invocation this result finalizes.
	InvocationID routedrun.InvocationID
	// TerminalStatus is the terminal outcome.
	TerminalStatus routedrun.InvokeJobResultStatus
	// StructuredResult is the bounded structured result JSON.
	StructuredResult string
	// ResultDigest is the canonical digest of StructuredResult.
	ResultDigest string
	// ArtifactReferences are relative paths under the run artifact root.
	ArtifactReferences []string
	// HMAC is the hex-encoded HMAC-SHA256 over the canonical event fields,
	// keyed by the attempt's control key. Empty or invalid => rejected.
	HMAC string
}

ResultEvent is the terminal job-result event. The supervisor finalizes success ONLY from a verified result event for the active lease. A container exiting zero does NOT synthesize a ResultEvent.

type ResultStore 

type ResultStore interface {
	// SaveInvokeJobResult persists a terminal result. It MUST be idempotent: a
	// second call for the same run with the same terminal status is a no-op.
	SaveInvokeJobResult(ctx context.Context, result *routedrun.InvokeJobResult) error
	// GetInvokeJobResult loads the terminal result for a run. Returns
	// routedrun.ErrNotFound when no result has been committed.
	GetInvokeJobResult(ctx context.Context, runID routedrun.RunID) (*routedrun.InvokeJobResult, error)
}

ResultStore persists the terminal InvokeJobResult for a run. It is the protected result store referenced by the T02 types. The supervisor writes a result ONLY after the durable state transition (CAS on the attempt) commits.

type RunOptions 

type RunOptions struct {
	// ResumeFrom is an optional checkpoint ID. When set, the worker skips
	// all completed phases before the checkpoint and resumes from the next
	// uncommitted phase.
	ResumeFrom string

	// TargetTurns is the number of work turns to execute before finalize.
	// Zero means the default (20 work turns + 1 final = 21 total). When set
	// higher (e.g. 100), the worker repeats the read/analyze/cross-reference/
	// compile cycle until the turn count reaches the target, then finalizes.
	// The minimum effective value is 21 (the default run).
	TargetTurns int
}

RunOptions configures a Run execution.

type Supervisor 

type Supervisor struct {
	// contains filtered or unexported fields
}

Supervisor is the durable, request-context-independent lifecycle supervisor.

All public methods are safe for concurrent use. State transitions go through CAS on the DurableStore; audit events are published only after the CAS commits; finalization/cancellation/cleanup are idempotent under races.

func NewSupervisor 

func NewSupervisor(
	store DurableStore,
	results ResultStore,
	journals ControlJournalFactory,
	clock routedrun.Clock,
	stateRoot string,
	opts ...SupervisorOption,
) (*Supervisor, error)

NewSupervisor constructs a Supervisor backed by the given durable store, result store, control-journal factory, and clock. The supervisor is independent of any CLI request context: callers invoke its methods from the daemon's post-admission path and from the restart reconciliation path.

func (*Supervisor) Cancel 

func (s *Supervisor) Cancel(ctx context.Context, attemptID routedrun.AttemptID) error

Cancel finalizes the attempt as CANCELLED. Idempotent: a second call on an already-CANCELLED attempt returns nil; on a different terminal state it returns ErrAlreadyTerminal.

func (*Supervisor) CheckStall 

func (s *Supervisor) CheckStall(ctx context.Context, attemptID routedrun.AttemptID, env routedrun.TimeEnvelope) (bool, error)

CheckStall reports whether the attempt is stalled at the current monotonic time. It is the test/inpection seam for the stall timer: the daemon polls it (or a timer goroutine fires it) to drive stall-driven finalization.

CheckStall is safe for concurrent use and does not mutate durable state.

func (*Supervisor) ClaimForRun 

func (s *Supervisor) ClaimForRun(ctx context.Context, runID routedrun.RunID, _ routedrun.InvocationID) (routedrun.AttemptID, error)

ClaimForRun acquires the active lease for an already-resolved run. This is the lower-level entry point the daemon calls after AdmitInvocation has committed the durable READY launch-intent and resolved the runID.

ClaimForRun is idempotent on the run: if a non-terminal attempt with an active lease already exists, it re-establishes in-memory tracking for that attempt and returns its ID without creating a new attempt or a new lease.

func (*Supervisor) Finalize 

func (s *Supervisor) Finalize(ctx context.Context, attemptID routedrun.AttemptID) error

Finalize is the idempotent terminal transition called when the container exits or the lease expires. It does NOT mark success unless a verified result event has been committed for the active lease.

func (*Supervisor) HandleCheckpoint 

func (s *Supervisor) HandleCheckpoint(ctx context.Context, attemptID routedrun.AttemptID, event CheckpointEvent) error

HandleCheckpoint accepts an authenticated checkpoint/artifact commit. A checkpoint commit counts as accepted activity (durable forward progress).

func (*Supervisor) HandleHTTPEnd 

func (s *Supervisor) HandleHTTPEnd(ctx context.Context, attemptID routedrun.AttemptID, leaseID routedrun.LeaseID) error

HandleHTTPEnd records the end of an in-flight HTTP operation.

func (*Supervisor) HandleHTTPStart 

func (s *Supervisor) HandleHTTPStart(ctx context.Context, attemptID routedrun.AttemptID, leaseID routedrun.LeaseID) error

HandleHTTPStart records the start of an in-flight HTTP operation.

func (*Supervisor) HandleMCPEnd 

func (s *Supervisor) HandleMCPEnd(ctx context.Context, attemptID routedrun.AttemptID, leaseID routedrun.LeaseID) error

HandleMCPEnd records the end of an in-flight MCP operation.

func (*Supervisor) HandleMCPStart 

func (s *Supervisor) HandleMCPStart(ctx context.Context, attemptID routedrun.AttemptID, leaseID routedrun.LeaseID) error

HandleMCPStart records the start of an in-flight MCP operation.

func (*Supervisor) HandleModelEnd 

func (s *Supervisor) HandleModelEnd(ctx context.Context, attemptID routedrun.AttemptID, leaseID routedrun.LeaseID) error

HandleModelEnd records the end of an in-flight model call.

func (*Supervisor) HandleModelStart 

func (s *Supervisor) HandleModelStart(ctx context.Context, attemptID routedrun.AttemptID, leaseID routedrun.LeaseID) error

HandleModelStart records the start of an in-flight model call. While any governed operation is in flight, the stall timer is bounded by the operation deadline, not the raw stall timeout.

func (*Supervisor) HandleResult 

func (s *Supervisor) HandleResult(ctx context.Context, attemptID routedrun.AttemptID, event ResultEvent) error

HandleResult accepts the terminal job-result event. It finalizes the attempt per the result's terminal status, ONLY from a verified result event for the active lease.

func (*Supervisor) Reconcile 

func (s *Supervisor) Reconcile(ctx context.Context, runID routedrun.RunID) error

Reconcile is the daemon-restart reconciliation entry point. It:

  • Reads the control journal for each attempt of the run and replays events to reconstruct state.
  • If an active (non-terminal) attempt has NO committed terminal event in its journal: revoke the lease and mark FAILED with reason "daemon_restart" (ambiguous active lease). Never blindly re-invoke work.
  • If a terminal event WAS committed before crash: accept it; do not replay work.
  • Preserve safe checkpoint/artifact state for B39 continuation (no action needed - checkpoints are durable and never mutated).
  • Reconcile active-time segment state: if the workflow is fully PAUSED or NEEDS_REPLAN, conservatively close any open active segment WITHOUT charging wall time (frozen states do not accrue). If PAUSE_REQUESTED, accrue the elapsed wall time since the open segment start (it is an accruing state). If RUNNING, accrue the elapsed wall time since the open segment start and close the segment conservatively (exactly once).

func (*Supervisor) TrackProgress 

func (s *Supervisor) TrackProgress(_ context.Context, attemptID routedrun.AttemptID, p ProgressEvent) error

TrackProgress accepts an authenticated progress/heartbeat event. It counts as liveness evidence ONLY when the HMAC verifies against the attempt's control key and the lease matches the active lease.

func (*Supervisor) UnauthenticatedActivity 

func (s *Supervisor) UnauthenticatedActivity(_ context.Context, _ routedrun.AttemptID, _ string) error

UnauthenticatedActivity records an unauthenticated activity signal (stdout/stderr line, process-existence poll, unauthenticated file write). It does NOT reset the stall timer. It exists so callers can record the signal for observability without it counting as progress.

type SupervisorOption 

type SupervisorOption func(*Supervisor)

SupervisorOption configures a Supervisor.

func WithAuditLogger 

func WithAuditLogger(log AuditLogger) SupervisorOption

WithAuditLogger injects an audit logger. If not set, a no-op logger is used.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.