---
id: 12071
title: 'Sub 5: Standalone refreshGoldenPath() orchestrator method + npm script'
state: CLOSED
labels:
  - enhancement
  - ai
  - architecture
  - model-experience
assignees: []
createdAt: '2026-05-27T01:43:16Z'
updatedAt: '2026-05-27T01:59:09Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12071'
author: neo-opus-ada
commentsCount: 1
parentIssue: 12065
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-27T01:59:05Z'
---
# Sub 5: Standalone refreshGoldenPath() orchestrator method + npm script

## Parent Epic

#12065 — Sub 5 of 9. **Depends on Sub 3** (orchestrator method substrate).

## Premise

Per Discussion #12062 §2.9 (operator-direct workflow): operator reads `sandman_handoff.md` → sees top-5 weighted items → does 5 PRs → wants cheap refresh of the strategic brief without paying the full REM cycle cost. Full REM = MINUTES × N gemma calls; refresh = ~10s-1min (graph-walk + 1 interpretive LLM call). 10-60× cost asymmetry.

Currently the orchestrator's `'golden-path'` cadence task bundles with the dream task via `dependencies: ['dream']` — it only fires WITHIN the cadence cycle. There's no operator-invocable refresh-only path.

## Prescription

New method on `Orchestrator.mjs`:

```js
async refreshGoldenPath({reason}) {
    // No gemma extraction; just Hybrid GraphRAG over current graph state + 1 interpretive call
    return withHeavyMaintenanceLease(async () => {
        const remRun = this.openRemRun({runId: crypto.randomUUID(), reason, mode: 'refresh'});
        try {
            await GoldenPathSynthesizer.synthesizeGoldenPath({
                repoEnrichmentEnabled: this.goldenPathRepoEnrichmentEnabled
            });
            this.closeRemRun(remRun, 'completed');
        } catch (e) {
            this.closeRemRun(remRun, 'failed', {error: e});
            throw e;
        }
    }, {owner: 'orchestrator-golden-path-refresh', reason});
}
```

Add npm script `ai:refresh-golden-path` invoking `runSandman.mjs refresh` (Sub 4's mode-selector).

## Acceptance Criteria

- [ ] AC1: `Orchestrator.refreshGoldenPath()` method shipped
- [ ] AC2: Method runs ONLY GoldenPathSynthesizer (no gemma extraction; no decay; no apoptosis)
- [ ] AC3: Method records REM run/stage state via Sub 2's substrate (`mode: 'refresh'` distinguishes from full cycle)
- [ ] AC4: Method honors heavy-maintenance-lease semantics (defers if another heavy task holds lease)
- [ ] AC5: npm script `ai:refresh-golden-path` lands (preferred operator UX; not just `ai:run-sandman refresh`)
- [ ] AC6: Unit + integration tests covering: refresh-only mode, refresh-during-active-dream-task (defer behavior), refresh-failure-recovery
- [ ] AC7: Documentation update at `learn/agentos/` describing the cheap-refresh UX + when to use it (post-PR-merge refresh use case)

## Avoided Traps

- ❌ Trigger any gemma extraction in refresh path — defeats the 10-60× cost asymmetry
- ❌ Skip lease semantics — risks concurrent graph mutation during heavy work
- ❌ Hide behind `executeRemCycle({mode: 'refresh-only'})` — separate method is clearer + matches Discussion §2.9 design

## Related

- Epic #12065
- Discussion #12062 §2.9 (cheap-refresh UX argument; split-and-recompose principle) + OQ2 [RESOLVED_TO_AC]
- Sub 3 (executeRemCycle peer method on same orchestrator)

## Timeline

- 2026-05-27T01:43:16Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-05-27T01:43:17Z @neo-opus-ada added the `enhancement` label
- 2026-05-27T01:43:17Z @neo-opus-ada added the `ai` label
- 2026-05-27T01:43:18Z @neo-opus-ada added the `architecture` label
- 2026-05-27T01:43:18Z @neo-opus-ada added the `model-experience` label
- 2026-05-27T01:45:29Z @neo-opus-ada added parent issue #12065
- 2026-05-27T01:50:32Z @neo-opus-ada unassigned from @neo-opus-ada
- 2026-05-27T01:56:59Z @neo-opus-ada assigned to @neo-opus-ada
### @neo-opus-ada - 2026-05-27T01:59:04Z

Closing as **not planned** — V-B-A on operator pushback confirms the standalone refresh path already exists:

- **`ai/scripts/runners/runGoldenPath.mjs`** — invokes `DreamService.synthesizeGoldenPath()` directly with `autoDream=false / autoSummarize=false / autoGoldenPath=false` (bypasses daemon auto-queue, exactly the cheap-refresh contract from Discussion #12062 §2.9).
- **`ai/services/graph/GoldenPathSynthesizer.mjs`** — the synthesizer this runner targets.

The Sub-5 prescription was authored at graduation time without V-B-A on present substrate. Operator-confirmed: 'the orchestrator has a standalone golden path service. that is ENOUGH.'

If a thin npm-script alias (`ai:refresh-golden-path → node ai/scripts/runners/runGoldenPath.mjs`) is wanted later as UX polish, that's a chore-sized follow-up, not Epic-sized substrate work; not filing speculatively.

— @neo-opus-ada (Neo Claude Opus)

- 2026-05-27T01:59:05Z @neo-opus-ada closed this issue
- 2026-05-27T01:59:09Z @neo-opus-ada unassigned from @neo-opus-ada
- 2026-05-27T02:06:11Z @neo-gpt cross-referenced by #12065
- 2026-05-27T02:10:15Z @neo-opus-ada cross-referenced by PR #12076
- 2026-05-27T02:23:15Z @neo-opus-ada cross-referenced by #12078
- 2026-05-27T02:25:15Z @neo-opus-ada cross-referenced by PR #12079
- 2026-05-27T12:14:09Z @tobiu referenced in commit `394c531` - "feat(ai): gemma4 REM-pipeline benchmark harness + keep_alive probe (#12074) (#12076)

* feat(ai): add gemma4 REM-pipeline benchmark harness + keep_alive probe (#12074)

Phase 1 of Epic #12065 Sub 8 — code-only ship; Phase 2 baseline numbers
land after operator runs on gemma4-equipped host.

Substrate added:

- `ai/scripts/benchmark/gemma4-rem-benchmark.mjs` — per-bucket cost
  characterization. Streams synthetic prompts at 4 size buckets
  (~5K / ~30K / ~100K / ~200K tokens) and records TTFT / TTLT / tps per
  call. Routes via `buildGraphProvider` so it mirrors the production
  SemanticGraphExtractor path, not a parallel one.

- `ai/scripts/benchmark/keep-alive-probe.mjs` — empirical V-B-A of provider
  KV-cache reuse via the `keep_alive` parameter. Two back-to-back identical
  calls; compares TTFT delta to decide whether reuse is active and whether
  `keep_alive` is the controlling knob.

- `ai/scripts/benchmark/helpers/stats.mjs` — pure median / percentile /
  summarize helpers. Lifted out of the harness so the math is provably
  correct independent of (LLM-dependent) measurement loops.

- `learn/agentos/gemma4-rem-benchmark.md` — measurement protocol +
  baseline-table-to-be-filled + integration recommendations decision tree
  for Sub 3 + Sub 7.

- `test/playwright/unit/ai/scripts/benchmark/stats.spec.mjs` — 16-case unit
  coverage for stats helpers (odd/even/empty/non-array median; nearest-rank
  p95 boundary cases; error-run filtering; n<5 omits p95).

- `package.json` — `ai:benchmark-gemma4` + `ai:probe-keep-alive` aliases.

Substrate V-B-A finding banked in doc + commit body, since the operator
likely doesn't know: `ai/provider/Ollama.mjs:108` hardcodes
`keep_alive: "1h"` in `generate()` ONLY. Both `Ollama.stream()` AND
`OpenAiCompatible.stream()` drop the param — if operator runs gemma via
the openAiCompatible host (current config default), the production
streaming path may silently lose KV-cache reuse. Probe will confirm.

Self-correction lesson: V-B-A present substrate BEFORE lane-claim on any
ticket, including tickets I authored myself at graduation time. Closing
#12071 from the same Epic for exactly this reason — its prescription was
duplicating existing `ai/scripts/runners/runGoldenPath.mjs`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply-suppressed>

* fix(ai): address PR #12076 cycle-1 review — graph provider routing + percentile + keep_alive prose (#12074)

Addresses @neo-gpt cycle-1 CHANGES_REQUESTED on PR #12076 (3 required actions):

1. **Provider routing bug** — scripts passed `aiConfig.modelProvider` to
   `buildGraphProvider`, but with PR #12061 landing the chat-vs-graph
   provider axis split, default `modelProvider: gemini` causes
   `buildGraphProvider: unsupported modelProvider 'gemini'` at preflight
   before any measurement. Fix: inline the same resolution shape as
   PR #12061's `resolveGraphModelProvider` (`aiConfig.graphProvider` with
   fallback to `'openAiCompatible'` unless `modelProvider === 'ollama'`).
   TODO post-#12061-merge: replace inline logic with shared helper import.

   No-LLM smoke verified:
       node ai/scripts/benchmark/gemma4-rem-benchmark.mjs --size small \
           --iterations 0 --warmup 0 --output /tmp/gemma4-smoke.json
   now resolves `Graph provider: openAiCompatible (chat modelProvider: gemini)`
   and writes the empty-runs JSON cleanly. Same fix applied to
   keep-alive-probe.mjs.

   Result metadata now exposes both axes: `graphProvider` (the routing
   axis) + `chatModelProvider` (the orthogonal generic axis).

2. **Percentile off-by-one** — `Math.floor(p * N)` returned the wrong rank
   for NIST nearest-rank semantics. For [1..100] and p=0.95: Math.floor
   gives 95 (sorted[95] = 96), but NIST ordinal-rank = ceil(p * N) gives
   95 (sorted[94] = 95). Fixed to `Math.ceil(p * N) - 1` with clamp via
   `Math.max(0, ...)` for the p=0 edge case. JSDoc expanded with explicit
   NIST formula citation. Test corrected to assert 95 (not 96) for p95
   of [1..100]. Other test cases (p50/p=0/p=1/single-element) unchanged
   — they already passed both formulas.

3. **keep_alive prose drift** — earlier prose said both Ollama.stream()
   AND OpenAiCompatible.stream() "drop" keep_alive. Mechanically broad:
   `OpenAiCompatible.stream()` uses `preparePayload()` which
   `Object.assign(payload, clonedOptions)` — so caller-supplied keep_alive
   IS mechanically propagated. The unverified residual is whether the
   deployed server (LM Studio, llama.cpp, vLLM, Ollama-`/v1/...`) HONORS
   the non-standard `keep_alive` extension. Updated:
   - `learn/agentos/gemma4-rem-benchmark.md` table rows for Ollama.stream
     and OpenAiCompatible.stream
   - `keep-alive-probe.mjs` @summary header

Test evidence:
- `npm run test-unit -- test/playwright/unit/ai/scripts/benchmark/stats.spec.mjs`
  → 16/16 passed (570ms)
- `node ai/scripts/benchmark/gemma4-rem-benchmark.mjs --help` clean
- `node ai/scripts/benchmark/keep-alive-probe.mjs --help` clean
- `node ai/scripts/benchmark/gemma4-rem-benchmark.mjs --size small
   --iterations 0 --warmup 0 --output /tmp/gemma4-smoke.json` clean
  (no preflight provider-dispatch failure)

* fix(ai): narrow keep-alive probe scope — native Ollama early-exit per #12076 cycle-2 review (#12074)

Addresses @neo-gpt cycle-2 CHANGES_REQUESTED on PR #12076 (1 of 2 required actions; body update follows):

V-B-A on Ollama.preparePayload() lines 91-92: arbitrary remaining
`options` are nested under `payload.options`, NOT top-level. Native
Ollama `/api/chat` reads `keep_alive` at TOP LEVEL of the request body,
so caller-supplied `keep_alive` via `provider.stream(messages,
{keep_alive})` becomes `payload.options.keep_alive` and is silently
ignored by Ollama. The probe's `keep_alive=0` control comparison would
be meaningless for the native Ollama path.

OpenAI-compatible providers are fine: `OpenAiCompatible.preparePayload()`
line 105 uses `Object.assign(payload, clonedOptions)`, so caller-
supplied `keep_alive` IS top-level in the JSON. The remaining V-B-A
target for OpenAI-compat is whether the deployed server HONORS the
non-standard `keep_alive` extension — that's what this probe still
characterizes.

Fix: early-exit on native Ollama with explicit message naming the
preparePayload nesting + the workaround (rely on `Ollama.generate()`
callsites which write `keep_alive` top-level at line 108). Follow-up
SDK fix to patch `Ollama.stream()` for top-level `keep_alive` injection
is tracked separately (out of scope for this benchmark PR).

Doc updates (`learn/agentos/gemma4-rem-benchmark.md`):
- Substrate V-B-A findings table now anchors `Ollama.mjs:91-92`
  (preparePayload nesting) instead of `Ollama.mjs:267-276` (stream() —
  not the actual source of the keep_alive issue).
- Interpretation matrix scoped to "OpenAI-compatible path only" with
  cross-reference to the native Ollama early-exit rationale.
- Implication paragraph narrowed: probe characterizes OpenAI-compat
  server-honor on the streaming path; native Ollama streaming requires
  SDK patch.

Probe @summary header updated to match (mirror of the doc V-B-A table
rows for in-file substrate consultation).

Empirical sanity-check (against operator's live LM Studio gemma-4-31b-it
on http://127.0.0.1:1234, graphProvider=openAiCompatible default):
- `--mode reuse`: TTFT call-1 2520ms → call-2 235ms (91% faster). Probe
  works; KV-cache reuse appears ACTIVE on the operator's deployed
  OpenAI-compat server. (Not committing this number to the doc —
  Phase-2 baselines remain operator-owned per design.)

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-27T12:15:53Z @tobiu referenced in commit `93c6a91` - "refactor(ai): delete dead ai/scripts/runners/runGoldenPath.mjs (#12078) (#12079)

* refactor(ai): delete dead ai/scripts/runners/runGoldenPath.mjs (#12078)

V-B-A on operator signal 2026-05-27 02:18Z:
> "ai/scripts/runners/runGoldenPath.mjs already exists. => i assume the
>  orchestrator is NOT using it. if true, this script => DELETE."

Confirmed: zero callers. Orchestrator goes direct to
GoldenPathSynthesizer.synthesizeGoldenPath() (Orchestrator.mjs:714-718)
via the injected synthesizer instance; runGoldenPath.mjs only chained
through deprecated DreamService.synthesizeGoldenPath passthroughs (lines
264 + 348), themselves @deprecated. No npm script. No test coverage.
Discussion #11076 line 46 already documented as "dev/test tool, not
production scheduling primitive."

Replaces the closed Sub 5 #12071 in spirit — Sub 5 proposed adding a
standalone refreshGoldenPath() method to the orchestrator; the correct
substrate move is to delete the dead runner (this PR) and let the
orchestrator's existing 'golden-path' cadence task remain the canonical
entry-point.

Living-doc reference at learn/guides/fundamentals/CodebaseOverview.md:441
removed; the runSandman.mjs bullet on the preceding line now carries a
clarifying note that the orchestrator owns golden-path synthesis directly.

Out of scope: the runSandman.mjs path on line 440 still says
'buildScripts/ai/runSandman.mjs' but the actual location is
'ai/scripts/runners/runSandman.mjs' — pre-existing doc drift not
introduced by this PR. Operator's separate signal "runSandman => DELETE
once orchestrator is feature complete" makes a follow-up doc-fix
short-lived anyway.

* docs(startup): remove dangling runGoldenPath.mjs bullet from AGENTS_STARTUP §step 6 (#12078)

Addresses @neo-gpt cycle-1 CHANGES_REQUESTED on PR #12079.

AGENTS_STARTUP.md is turn-loaded substrate (always loaded into agent
context at boot). Line 120 still pointed at the deleted
`buildScripts/ai/runGoldenPath.mjs` runner, creating a broken
manual-remediation instruction for fresh agents.

Per /turn-memory-pre-flight decision:
- Change class: subtractive (removing operator-script reference)
- Substrate type: turn-loaded (high agent-behavior impact)
- Replacement substrate: documented inline — golden-path-only refresh
  currently requires full REM via `npm run ai:run-sandman` OR rolls into
  the next orchestrator cadence; orchestrator-direct refresh entrypoint
  pending Epic #12065 closeout
- Decision: justified (removes broken reference; clarifies workflow gap)

The rewritten bullet preserves the original workflow-context for future
agents trying to V-B-A what golden-path-only refresh paths exist, and
explicitly cites #12078 + Epic #12065 for the substrate trajectory.

Companion edit to:
- ai/scripts/runners/runGoldenPath.mjs (deleted in PR #12079 commit bdbfac586)
- learn/guides/fundamentals/CodebaseOverview.md:441 (already updated in same PR)

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"

