LearnNewsExamplesServices
Frontmatter
id11511
titleClassify Golden Path as light orchestrator maintenance
stateClosed
labels
enhancementaiarchitectureperformancemodel-experience
assigneesneo-gpt
createdAtMay 17, 2026, 1:50 AM
updatedAtMay 17, 2026, 2:24 AM
githubUrlhttps://github.com/neomjs/neo/issues/11511
authorneo-gpt
commentsCount0
parentIssue11503
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 17, 2026, 2:24 AM

Classify Golden Path as light orchestrator maintenance

Closedenhancementaiarchitectureperformancemodel-experience
neo-gpt
neo-gpt commented on May 17, 2026, 1:50 AM

Context

The operator observed this orchestrator log while the heavy-maintenance mutex workstream is active:

[2026-05-16T23:25:26.679Z] [PID:18927] [INFO] [Orchestrator] Deferring golden path synthesis;

The concern is that Sandman / DreamService is expensive, while Golden Path synthesis is comparatively cheap. Treating them as the same scheduling class can delay a lightweight frontier refresh behind unrelated heavyweight work and can make the daemon appear more blocked than it really is.

V-B-A evidence before filing:

  • rg -n "Deferring golden path|golden path|GoldenPath|sandman|DreamService|heavy" ai buildScripts package.json located the deferral path in ai/daemons/Orchestrator.mjs.
  • ai/daemons/Orchestrator.mjs:43-49 places GOLDEN_PATH_TASK_NAME inside DEFAULT_HEAVY_MAINTENANCE_TASK_NAMES next to summary, kbSync, primary-dev-sync, and dream.
  • ai/daemons/Orchestrator.mjs:470-488 records all such skips as heavy-maintenance-backpressure.
  • ai/daemons/Orchestrator.mjs:631-645 routes GOLDEN_PATH_TASK_NAME through the same executeMaintenanceTask(...) wrapper.
  • ai/daemons/services/GoldenPathSynthesizer.mjs:50-115 shows the task does real work: Chroma summary/graph reads, one embedding, and SQLite graph ranking.
  • ai/daemons/services/GoldenPathSynthesizer.mjs:205-239 shows the optional short MLX interpretation.
  • ai/daemons/services/GoldenPathSynthesizer.mjs:474-480 rewrites sandman_handoff.md and anchors frontier links.
  • Closed #11389 explicitly left daemon-side improvements out of scope and named Golden Path invocation locking / daemon policy as a separate daemon concern.
  • Live duplicate sweep found no open equivalent ticket for golden path orchestrator deferring heavy maintenance.

The Problem

The current scheduling policy uses one binary category: heavyMaintenanceTaskNames. That category conflates at least two different concerns:

  1. Heavy / memory-pressure tasks: session summarization, Knowledge Base sync, primary checkout sync, and DreamService graph extraction.
  2. Light frontier refresh tasks: Golden Path synthesis, which reads recent graph/vector state, computes top issues, optionally asks MLX for a short strategic brief, writes sandman_handoff.md, and refreshes frontier guidance.

Golden Path is not free, so it should not be treated as a harmless no-op. But it is materially cheaper than full Sandman / DreamService and should not participate in the same all-against-all heavyweight mutex without an explicit policy reason.

The Architectural Reality

The orchestrator already has the right place to express this distinction: ai/daemons/Orchestrator.mjs owns cadence and task conflict policy, while ai/daemons/TaskDefinitions.mjs owns stable task identities and labels.

The current implementation makes golden-path both:

  • deferred by every active heavy task, and
  • a blocker for every later heavy task in the same poll if it starts first.

That second side-effect is especially suspicious: a lightweight Golden Path refresh should not be able to postpone a due Knowledge Base sync or DreamService run merely because it was checked first.

The Fix

Refine orchestrator scheduling policy so Golden Path is not classified as a full heavyweight maintenance task.

Expected shape:

  • Split the current binary heavyMaintenanceTaskNames policy into clearer task classes, or otherwise remove GOLDEN_PATH_TASK_NAME from the all-against-all heavyweight blocker set.
  • Preserve protection against unsafe overlap where justified, especially DreamService -> Golden Path ordering if Dream is actively mutating graph inputs.
  • Keep log and health outcome semantics accurate: if Golden Path is deferred, the reason should name the specific dependency / freshness guard, not generic heavy-maintenance-backpressure unless it really is using that class.
  • Add focused Orchestrator unit coverage proving the intended policy.

Contract Ledger Matrix

Target Surface Source of Authority Proposed Behavior Fallback Docs Evidence
Orchestrator task conflict policy ai/daemons/Orchestrator.mjs Golden Path is treated as light frontier-refresh work, not as an all-against-all heavy blocker Defer only for explicit unsafe dependencies such as active Dream graph mutation Inline JSDoc / test names are sufficient unless behavior becomes operator-facing config Unit tests in test/playwright/unit/ai/daemons/Orchestrator.spec.mjs
Health outcome reason codes HealthService.recordTaskOutcome(...) consumers Golden Path skips use an accurate reason code Existing heavy-maintenance-backpressure remains for true heavy tasks Existing health surface Unit assertions on task outcome payloads
sandman_handoff.md writer behavior GoldenPathSynthesizer.synthesizeGoldenPath() Single run remains canonical writer for Golden Path output Existing write path remains unchanged #11389 and #11503 context Existing synthesizer behavior + no new writer

Acceptance Criteria

  • GOLDEN_PATH_TASK_NAME no longer participates in the same all-against-all heavyweight blocker set as summary, kbSync, primary-dev-sync, and dream.
  • A due Golden Path run does not block later due heavyweight maintenance tasks in the same poll.
  • If Golden Path is still deferred behind DreamService, the deferral reason is explicit and tested as Dream/freshness ordering, not generic heavyweight equivalence.
  • Existing heavy-task mutual exclusion remains intact for at least summary vs kbSync and already-running heavy task cases.
  • Focused Orchestrator unit tests cover the new behavior.
  • No changes to GoldenPathSynthesizer internals unless a direct policy need is discovered during implementation.

Out of Scope

  • Rewriting Golden Path synthesis internals.
  • Changing the default one-hour cadence.
  • Changing ai:run-sandman manual behavior.
  • Introducing a new daemon process.
  • Retiring the heavy-maintenance lease primitive from #11505.

Avoided Traps

  • Treat Golden Path as zero-cost — rejected. It touches Chroma, embeddings, SQLite graph links, optional MLX, and sandman_handoff.md.
  • Leave one binary heavy bucket forever — rejected. The current symptom is caused by category collapse, not by a missing interval.
  • Run Golden Path during active Dream graph mutation without thought — rejected. The light classification should not create partial-frontier races.
  • Fix by lowering log severity only — rejected. The current log is already INFO; the issue is scheduling semantics.

Related

Handoff Retrieval Hints

Search for Deferring golden path synthesis heavy-maintenance-backpressure GoldenPathSynthesizer orchestrator light frontier refresh.

tobiu referenced in commit 1f5ab3b - "feat(ai): classify golden path as light maintenance (#11511) (#11512) on May 17, 2026, 2:24 AM
tobiu closed this issue on May 17, 2026, 2:24 AM