Method RecoverRun

internal/task/force_ops.go:282–362

RecoverRun terminalizes a needs_attention run and queues one fresh child to resume work.

(
	ctx context.Context,
	runID string,
	req RecoverRunRequest,
	actor ActorContext,
)

// RecoverRun terminalizes a needs_attention run and queues one fresh child to resume work.
func (m *Service) RecoverRun(
	ctx context.Context,
	runID string,
	req RecoverRunRequest,
	actor ActorContext,
) (*RetryRunResult, error) {
	if err := m.requireForceRunAuthority(actor); err != nil {
		return nil, err
	}
	normalized, err := normalizeRecoverRunRequest(req)
	if err != nil {
		return nil, err
	}
	source, taskRecord, err := m.loadRunWithTask(ctx, runID)
	if err != nil {
		return nil, err
	}
	if err := m.requireForceRunRate(actor, taskRecord.ID); err != nil {
		return nil, err
	}
	if source.Status.Normalize() != TaskRunStatusNeedsAttention {
		suggested := fmt.Sprintf("agh task inspect %s", source.ID)
		if source.Status.Normalize() == TaskRunStatusFailed {
			suggested = fmt.Sprintf("agh task retry %s", source.ID)
		}
		return nil, forceRunDiagnosticError(
			diagnosticcontract.CodeTaskRunNotRecoverable,
			"Task run cannot be recovered",
			fmt.Sprintf(
				"Run %s is %s; only needs_attention runs can be recovered.",
				source.ID,
				source.Status.Normalize(),
			),
			diagnosticcontract.SeverityError,
			suggested,
			map[string]any{runEvidenceIDKey: source.ID, leaseStatusKey: string(source.Status.Normalize())},
			ErrInvalidStatusTransition,
		)
	}
	if err := m.requireRetryChainDepth(ctx, source); err != nil {
		return nil, err
	}

	result, err := m.store.RecoverTaskRun(ctx, RecoverRunMutation{
		SourceRunID: source.ID,
		NewRunID:    m.newID("run"),
		Origin:      actor.Origin,
		Reason:      normalized.Reason,
		Metadata:    normalized.Metadata,
		QueuedAt:    m.now().UTC(),
	})
	if err != nil {
		return nil, err
	}
	reconciledTask, err := m.reconcileTaskCascade(ctx, taskRecord.ID)
	if err != nil {
		return nil, err
	}