LearnNewsExamplesServices
Frontmatter
id9920
titleGolden Path issue-task failure envelope and requeue policy
stateClosed
labels
enhancementai
assigneesneo-gpt
createdAtApr 12, 2026, 3:23 PM
updatedAt3:18 PM
githubUrlhttps://github.com/neomjs/neo/issues/9920
authortobiu
commentsCount1
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtJun 6, 2026, 3:24 PM

Golden Path issue-task failure envelope and requeue policy

Closed v13.0.0/archive-v13-0-0-chunk-4 enhancementai
tobiu
tobiu commented on Apr 12, 2026, 3:23 PM

Golden Path issue-task failure envelope and requeue policy

Current Verified State (2026-06-03)

Live V-B-A refreshed #9920 against current source and issue state:

  • The original concern remains valid: autonomous Golden Path issue execution must not fail silently, crash the process without a durable record, or create an uncontrolled retry loop.
  • The original wording is stale. Current daemon task execution is owned by ai/daemons/orchestrator/Orchestrator.mjs, TaskStateService, and HealthService.recordTaskOutcome().
  • Current daemon tasks already have generic task lifecycle telemetry: running, completed, failed, and skipped.
  • REM/Sandman cycles already have durable phase/run-state envelopes via RemRunStateStore.
  • AgentOrchestrator still injects system:golden-path directives into Neo.ai.Agent, catches top-level failures, then rethrows. It does not define a stable per-issue outcome record or requeue policy.
  • AgentOrchestrator is not currently listed as an orchestrator daemon task in TaskDefinitions.mjs; any daemon-task integration must be explicit rather than assumed.
  • No direct successor PR or issue was found for #9920.

Problem

Current substrate can tell operators that a daemon task failed, and REM runs can describe pipeline phase failures. It still lacks the contract for an autonomous issue directive failure:

  • Which issueId failed?
  • Did the agent complete, block, trip the failure loop, hit a context/turn limit, crash, or exhaust the queue?
  • Should the issue remain urgent, be demoted, become blocked, or require human/peer handoff?
  • Where does the next Sandman/Golden Path cycle read that outcome?

Without that contract, any "requeue" implementation risks either silent suppression or retry storms.

Accepted Scope

Define and implement a durable Golden Path issue-task outcome envelope for AgentOrchestrator directives, plus a conservative requeue policy.

This ticket does not add automatic retries. It records the outcome and projects it into existing observability/handoff surfaces so the next cycle can reason from evidence.

Contract Ledger

Surface Contract
Primary owner AgentOrchestrator.execute() owns per-directive outcome recording for system:golden-path work it schedules into Neo.ai.Agent.
Durable outcome record Write append-only JSONL records under a configured local path, defaulting to .neo-ai-data/agent-orchestrator/golden-path-outcomes.jsonl. Each record must include runId, issueId, description, startedAt, completedAt, status, reasonCode, retryPolicy, error, and handoffMessageId when applicable.
Status vocabulary Allowed statuses: completed, failed, blocked, expired, exhausted, crashed. Do not invent free-form statuses.
Reason codes Minimum required reason codes: agent-uncaught-error, productive-failure-tripwire, turn-limit, context-limit, tool-failure, blocked-task-state, queue-exhausted, unknown.
Requeue policy Allowed values: preserve-urgency, demote-next-cycle, blocked-handoff, no-retry. Default for unknown failures is preserve-urgency; automatic immediate retry is forbidden in V1.
Health projection If HealthService is available, call recordTaskOutcome('agent-orchestrator', status, details) with the same stable outcome fields. If unavailable, the JSONL outcome record remains the source of truth.
A2A / handoff For blocked, expired, crashed, and repeated failed outcomes, emit a peer-visible handoff via the existing A2A/task-state path and include the resulting stable identifier in handoffMessageId where available.
Golden Path boundary Do not mutate Golden Path scoring directly in V1. Golden Path remains mathematically computed from graph state. The outcome record may be rendered as a visibility section or consumed by a later explicit policy ticket, but this ticket must not silently suppress an issue from future Golden Path output.
Daemon-task boundary Do not assume AgentOrchestrator is an orchestrator daemon task. If implementation adds it to TaskDefinitions.mjs, the PR must document that as an explicit scope addition and wire TaskStateService failure handling in the same PR.
Evidence Add focused tests for outcome schema, top-level catch/failure recording, queue-exhaustion recording, no-immediate-retry behavior, and health projection fallback when HealthService is unavailable.

Acceptance Criteria

  • AgentOrchestrator records a durable per-issue outcome for every scheduled Golden Path directive.
  • Top-level uncaught errors produce a failed or crashed outcome instead of only rethrowing without issue context.
  • Queue exhaustion produces an exhausted or completed outcome with issue context.
  • V1 never immediately retries a failed directive in-process.
  • Health projection uses HealthService.recordTaskOutcome('agent-orchestrator', ...) when available, with JSONL fallback as source of truth.
  • A2A/handoff output is produced for blocked/crashed/repeated-failure outcomes.
  • Tests cover the schema, failure path, queue-exhaustion path, retry-policy default, and health unavailable fallback.
  • Docs or JSDoc state that Golden Path scoring is not mutated by this V1.

Out of Scope

  • Automatic retry loops.
  • Golden Path scoring suppression/demotion without a separate explicit policy.
  • Adding a new daemon task unless the PR explicitly expands scope and wires TaskDefinitions.mjs / TaskStateService.
  • Human-owned merge/retry decisions.
  • Retrofitting historical failure records.

Related

  • Current task-state substrate: TaskStateService, HealthService.recordTaskOutcome(), Orchestrator.mjs
  • Current issue directive substrate: AgentOrchestrator.parseGoldenPath() / AgentOrchestrator.execute()
  • REM failure precedent: RemRunStateStore, learn/agentos/rem-state-model.md, learn/agentos/sandman-silent-failure-forensics.md

Origin Session ID: 95bf4a2b-d84e-4f70-945b-f558ba924d3a

Retrieval Hint: "AgentOrchestrator Golden Path issue outcome envelope requeue policy no retry storm"

tobiu added the enhancement label on Apr 12, 2026, 3:23 PM
tobiu added the ai label on Apr 12, 2026, 3:23 PM
tobiu referenced in commit ac4c724 - "feat(agent): record Golden Path outcomes (#9920) (#12615) on Jun 6, 2026, 3:24 PM