What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	13118
title	Lifecycle-first wake prompt contract and watchdog cadence
state	Closed
labels	enhancementaiarchitecturemodel-experience
assignees	neo-opus-vega
createdAt	Jun 13, 2026, 8:37 PM
updatedAt	Jun 13, 2026, 11:25 PM
githubUrl	https://github.com/neomjs/neo/issues/13118
author	neo-gpt
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 13, 2026, 11:25 PM

Lifecycle-first wake prompt contract and watchdog cadence

Closed v13.1.0/archive-v13-1-0-chunk-2 enhancementaiarchitecturemodel-experience

neo-gpt commented on Jun 13, 2026, 8:37 PM

Context

Operator feedback on 2026-06-13 surfaced a night-shift coordination failure: agents improved at claiming fresh lanes, but existing PR debt and review gates could fall out of the active cycle. The concrete symptom was an own/peer PR lifecycle miss while repeated wake messages kept emphasizing “claim an unclaimed lane” instead of first draining PR lifecycle obligations.

This ticket graduates the cheap first leaf from Discussion #13114: lifecycle-first wake prompt ordering plus watchdog/backlog cadence tuning. It deliberately does not bundle the heavier PR-state delivery watcher.

Release classification: boardless — Agent OS coordination hardening, not a declared v13 release blocker.

Duplicate / freshness evidence:

Live latest-open sweep at 2026-06-13T18:35Z: checked latest 20 open issues; no equivalent lifecycle-first wake prompt / 20-30 minute watchdog cadence ticket found.
A2A in-flight sweep at 2026-06-13T18:35Z: checked latest 30 messages; no competing [lane-claim] or [lane-intent] for this graduation leaf.
Local exact sweep: wake prompt contract, lifecycle-first wake, watchdog cadence, own-PR CI-red, scarce cross-family, wake-routing; only unrelated wake-routing presence text surfaced.
KB semantic sweep found closed/superseded relatives (#11906, #11872) and deferred parent wake substrate (#11829), but no active duplicate for this first leaf.

The Problem

The current wake directive overweights backlog pickup. It tells an idle agent to “survey the open backlog … claim an unclaimed lane, and drive it implementation → test → PR,” which is directionally wrong when the highest-value action is already-created lifecycle work: own red CI, own PR waiting for review routing, assigned re-review, a peer PR blocked by our previous REQUEST_CHANGES, or a green peer PR where this agent is the scarce cross-family reviewer.

The noise side is separate but coupled: generic watchdog/backlog nudges arriving every few minutes make the backlog-first wording louder than the lifecycle substrate. Direct actionable messages should stay event-driven; generic watchdog nudges should move toward the operator-suggested 20-30 minute ballpark.

The Architectural Reality

ai/daemons/wake/daemon.mjs is the prompt-text authority; the current directive text includes the backlog-first “claim an unclaimed lane” phrasing around line 607.
ai/config.mjs owns heartbeat / wake cadence configuration surfaces, including swarm heartbeat target and cooldown leaves.
ai/daemons/orchestrator/services/SwarmHeartbeatService.mjs owns the swarm-heartbeat lane that emits heartbeat pulses on orchestrator cadence.
ai/services/memory-core/CoalescingEngineService.mjs owns wake digest coalescing, and ADR 0002 constrains coalescing caps. This ticket must distinguish watchdog cadence from coalescing semantics rather than silently changing both.
.agents/skills/post-review-pickup/references/post-review-pickup-workflow.md already says lifecycle queue before fresh lanes; the gap is the wake prompt contract and generic nudge cadence, not a rewrite of that skill.
.agents/skills/pull-request/references/ci-green-review-routing.md already forbids actionable reviewer routing before CI green; this ticket should preserve that split.

The Fix

Change the generic wake directive in ai/daemons/wake/daemon.mjs so it leads with a lifecycle-first queue before fresh-lane pickup.
Tune watchdog/backlog heartbeat cadence toward a 20-30 minute generic nudge window while preserving event-driven delivery for direct actionable messages.
Document the ADR 0002 relationship explicitly: either the new watchdog cadence sits above the existing coalescing cap, or the implementation must amend ADR 0002 in the same PR.
Keep the first leaf harness-agnostic and prose/config based. Do not add a central scheduler, scoreboard, PR lease, or PR-state transition watcher in this ticket.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback / Failure Mode	Docs / Evidence
Generic wake directive	`ai/daemons/wake/daemon.mjs`	Wake prompt orders work as lifecycle-first: own PR debt, review/re-review obligations, peer PRs blocked by this agent, scarce cross-family review, then fresh backlog.	If lifecycle state cannot be queried, directive must require a verified-empty or explicit blocked-state before fresh backlog pickup.	Unit/static test over directive text plus Discussion #13114 criteria mapping.
Watchdog/backlog cadence	`ai/config.mjs` + `SwarmHeartbeatService` / cooldown consumers	Generic watchdog/backlog nudges move toward 20-30 minutes; direct actionable messages remain event-driven.	If cadence is environment-overridden, docs/comments must still identify the default and the override path.	Focused unit/static config assertion; ADR 0002 disposition note.
Scarce cross-family review tier	Wake directive text only in this leaf	Agents are prompted to consider green peer PRs where they are a viable scarce cross-family reviewer before opening new same-family PRs.	Best-effort agent judgment or cheap active-roster proxy only; no central scheduler/scoreboard.	Acceptance scenario with peer-green PR and scarce reviewer context.
Delivery-trigger watcher	Out of scope in this leaf	No new PR-state watcher is implemented here.	File a separate follow-up only if prompt + cadence leaf fails post-merge validation.	Out-of-scope guard and post-merge validation.

Decision Record Impact

Depends-on ADR 0002. Implementation must explicitly choose and document one disposition:

aligned-with ADR 0002: 20-30 minute watchdog cadence is a layer above the existing 300s coalescing cap; no ADR amendment needed.
amends ADR 0002: if implementation changes the coalescing cap semantics, update ADR 0002 in the same PR.

Signal Ledger

GPT family: [AUTHOR_SIGNAL by @neo-gpt @ body-2026-06-13T18:28:18Z] — Discussion #13114 comment DC_kwDODSospM4BB9mS.
Claude family: [GRADUATION_APPROVED by @neo-opus-vega @ body-2026-06-13T17:41:59Z] conditional on four Step 2.5 partials becoming ACs — Discussion #13114 comment DC_kwDODSospM4BB9lp.

This is treated as Tier-1 high-blast workflow/wake policy, not Tier-2 core-value / critical-gate mutation.

Unresolved Dissent

None recorded at graduation time. Grace and Vega both converged on the lighter prompt + cadence leaf and explicitly deferred leases/read-model work as likely YAGNI until falsified.

Unresolved Liveness

Gemini and Fable-family signals were not present in this night-shift convergence window. Disposition: archive as liveness gap for this Tier-1 high-blast leaf; reopen or re-poll if either family reactivates and challenges the prompt/cadence shape before implementation lands.

Discussion Criteria Mapping

Authoritative ordering for wake / terminal-boundary lane discovery -> AC1, AC2, AC7.
Smallest enforceable substrate target -> AC3, AC4, AC5; first leaf is daemon.mjs prompt + cadence config/doc only.
Acceptance test using red/unstable own PR, simultaneous review request, and peer-green scarce-cross-family case -> AC7.
Wake cadence policy distinguishing actionable messages from watchdog/backlog nudges -> AC4.
Step 2.5 Architectural Step-Back sweep -> completed by Vega in Discussion #13114 comment DC_kwDODSospM4BB9lp; four partials are captured in AC3, AC4, AC5, AC6, and AC8.

Acceptance Criteria

AC1: The generic wake directive in ai/daemons/wake/daemon.mjs leads with lifecycle-first discovery before fresh backlog pickup.
AC2: The directive explicitly prioritizes at least: own red/unstable/stuck PRs; own green PRs needing review routing; requested review/re-review; peer PRs blocked by this agent’s prior REQUEST_CHANGES; peer green PRs where this agent is a scarce viable cross-family reviewer; then fresh unassigned backlog.
AC3: ai/daemons/wake/daemon.mjs is named in code comments or tests as the prompt-text authority so discussion / ticket / source wording cannot silently drift.
AC4: Generic watchdog/backlog nudge cadence defaults toward 20-30 minutes, while direct actionable message wakes remain event-driven.
AC5: ADR 0002 disposition is explicit: either the cadence sits above the 300s coalescing cap, or ADR 0002 is amended in the same PR.
AC6: The implementation remains harness-agnostic prose/config and does not encode Codex-, Claude-, Gemini-, or Antigravity-specific payload assumptions.
AC7: Focused tests or static assertions cover the three routing examples: own red/unstable PR, simultaneous review request, and peer-green scarce-cross-family review above fresh-lane pickup.
AC8: Scarce cross-family review remains best-effort / cheap heuristic only; no central scheduler, scoreboard, or persistent PR lease is introduced.
AC9: PR body documents delivery-trigger watcher deferral and includes post-merge validation to reassess whether prompt + cadence was sufficient.

Out of Scope

New PR-state transition delivery watcher for own-PR CI-red or peer-green events.
Per-PR lifecycle leases or an Active PR Cycle read model.
Central reviewer scheduler, scarcity scoreboard, or persistent reviewer quota system.
Changes to post-review-pickup unless a local wording reference is needed; that skill already encodes lifecycle-first behavior.
Any agent-executed gh pr merge path.

Avoided Traps

Do not solve prompt friction by adding a new dashboard/read model first; two or three cheap GitHub queries already reconstruct most lifecycle state.
Do not lower direct actionable wake delivery to 20-30 minutes; the operator complaint targets generic wake noise, not review/CI/blocker events.
Do not bundle the delivery-trigger watcher with the prompt/cadence leaf; Step 2.5 identified that as new daemon machinery with different state-mutability risk.

Related: #13114 Related: #11829 Related: #11906 Related: #11872

Origin Session ID: 0ed5b1b0-739e-40e5-93e6-21a2e567ec24

Retrieval Hint: lifecycle-first wake prompt contract watchdog cadence scarce cross-family reviewer Discussion #13114