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	13347
title	Research Codex wake submit path and retire one-shot harnesses
state	Closed
labels	bugaitestingregressionarchitecturemodel-experience
assignees	neo-gpt
createdAt	Jun 15, 2026, 3:03 PM
updatedAt	Jun 15, 2026, 3:59 PM
githubUrl	https://github.com/neomjs/neo/issues/13347
author	neo-gpt
commentsCount	5
parentIssue	13012
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[x] 13341 Isolate Codex wake matrix dry-run validation
closedAt	Jun 15, 2026, 3:59 PM

Research Codex wake submit path and retire one-shot harnesses

Closed v13.1.0/archive-v13-1-0-chunk-3 bugaitestingregressionarchitecturemodel-experience

neo-gpt commented on Jun 15, 2026, 3:03 PM

Context

Operator review on PR #13342 surfaced a premise-level blocker in the Codex wake lane:

Custom parseArgs() in new AI scripts is a repeated friction pattern.
The current operational symptom is not "we need more backend-only harnesses"; it is that real A2A wake messages can pile up in the Codex prompt field without submitting, while heartbeat wakes still submit.
The team has been adding dry-run validation logic without a visible cleanup/sunset plan for one-shot harness code.
There is no current ticket that forces a June-2026 Codex submit-path research/disposition before more repo substrate is added.

Release classification: post-release Agent Harness reliability hardening; belongs to the Agent Harness project, not the release board.

The Problem

#13287 remains the live bug: wake-eligible Codex A2A messages need proof that the prompt lands, submits, and starts a turn without operator Enter. PR #13342 tried to add a safe dry-run prerequisite (#13341), but the operator challenge is sharper: before the repo accumulates more validation harnesses, the team needs a current, evidence-backed decision on the actual Codex submit path.

The risk is repo pollution and wrong-priority work: backend-only tooling can become a substitute for fixing or reverting the user-visible wake-submit regression. A temporary harness can still be useful, but only with a bounded retirement/disposition rule and only after the route-level question is researched.

The Architectural Reality

V-B-A anchors checked before creation:

PR #13342 currently has an operator CHANGES_REQUESTED review questioning the premise and asking why the work is not either reverting to the stable path or fixing submit.
#13287 is open and assigned to @neo-gpt; it is the live L4 Codex prompt-submit/start-turn matrix bug.
#13341 is open and is the narrow dry-run validation ticket behind PR #13342.
#13067 is the historical codex-app-server adapter support lane; it is adjacent but not a current research/disposition ticket for submit behavior.
ADR 0016 (learn/agentos/decisions/0016-ai-script-cli-parser-convention.md) establishes Commander-first for new and actively touched AI script CLI surfaces; bespoke parseArgs() switch parsers are an anti-anchor unless justified.
ai/mcp/server/memory-core/openapi.yaml exposes codex-app-server and osascript as wake subscription adapter concepts, but the schema does not prove Codex Desktop submit/start-turn behavior.

The Fix

Create a research/disposition gate before adding or merging more Codex wake validation substrate:

Research the current Codex Desktop / Codex CLI submit surfaces used by the Agent Harness lane, with evidence that distinguishes prompt insertion from prompt submission / turn start. Treat steering mode as optional, not as the only valid path.
Decide the operational recovery path for #13287: revert active A2A message wakes to the previously stable osascript route, fix codex-app-server so it actually submits, or prove a third path with stronger evidence.
Disposition #13341 / PR #13342 explicitly: close, retarget, or keep only with a sunset/removal condition tied to #13287 completion.
If any AI script CLI remains in this path, convert it to Commander or document the ADR 0016 exception with tests proving why Commander cannot support the required semantics.
Update #13287 with the route decision and the live L4 evidence plan before claiming progress on the user-visible regression.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback / Edge Case	Docs	Evidence
Codex wake delivery route for A2A messages	#13287, operator review on #13342, wake subscription adapter schema	Route decision must be based on current submit/start-turn evidence, not backend dispatch success alone.	If app-server cannot submit reliably, prefer reverting the live wake path to the stable route until submit is fixed.	#13287 comment / wake prompt matrix update.	Live Codex prompt lands + submits + turn starts, or explicit rollback evidence.
One-shot validation harnesses (`ai:validate-codex-wake` / #13341)	#13341, PR #13342, Substrate Accretion Defense	Temporary harness code must have a retirement or retention trigger before merge.	If the harness is not needed after route recovery, close/drop it and port only durable evidence notes.	PR body / ticket body.	Explicit sunset/removal AC or closure comment.
AI script CLI parser shape	ADR 0016	New or actively touched AI lifecycle scripts use Commander-backed parsing by default.	Bespoke parser only with a documented exception and focused tests proving Commander cannot support the semantics.	ADR 0016 citation in PR body.	Unit tests for Commander parse/help/unknown-option behavior or justified exception.
#13287 live matrix	`ai/docs/wake-prompt-landing-matrix.md` + #13287	Matrix records route decision and L4 submit/start-turn evidence; dry-run/backend-only evidence is not promoted to L4.	Suppressed or backend-only events are marked upstream-invalid/partial, not submit proof.	#13287 matrix comment.	Controlled live artifact or operator-observed turn evidence.

Decision Record impact

Aligned with ADR 0016 (Commander-first AI script CLI parsing) and ADR 0020 (Agent Harness). No ADR amendment expected unless the Codex submit research changes the wake-substrate delivery model beyond route selection.

Acceptance Criteria

A research artifact or issue comment documents the current Codex submit/start-turn options with reproducible evidence, explicitly separating prompt insertion from prompt submission.
The active #13287 recovery path is selected: revert to stable osascript, fix codex-app-server submit, or document a third route with stronger evidence.
#13341 / PR #13342 receives an explicit disposition: close/drop, retarget, or retain with a concrete sunset/removal trigger after #13287 completion.
Any continuing validation CLI in this lane uses Commander per ADR 0016, or documents a narrow exception with focused tests.
#13287 is updated with the route decision and the evidence plan before any PR claims the Codex A2A wake regression is improved.

Out of Scope

Electron shell/build-root work (#13033).
Stale retry/read-state suppression (#13281 / #13285).
General heartbeat digest enrichment (#11829 / #11909 / #12612).
Broad Codex product strategy beyond the wake submit path needed for Agent Harness reliability.

Avoided Traps

Testing-tool accumulation as progress: adding a backend-only harness does not fix prompt submission.
Adapter-name assumption: codex-app-server existing in schema is not proof that it submits a Codex Desktop turn.
Parser recurrence: new custom parseArgs() repeats an already-decided ADR 0016 friction unless explicitly justified.
Permanent temporary substrate: one-shot validation code needs a sunset/retention rule before merge.

#13287 — live Codex A2A message wake submit regression.
#13341 / PR #13342 — isolated dry-run harness currently under operator CHANGES_REQUESTED.
#13067 — historical codex-app-server adapter support.
#13012 — Agent Harness parent epic.
ADR 0016 — Commander-first AI script CLI parser convention.

Duplicate / Claim Sweep

Live latest-open sweep: checked latest 20 open issues at 2026-06-15T13:02Z. Adjacent issues found (#13287, #13341, #13067 historical via all-state search), but no current ticket combines Codex submit-path research, #13342 harness disposition, and ADR 0016 parser correction.

A2A in-flight sweep: list_messages({status:'all', limit:30}) at 2026-06-15T13:02Z showed no recent [lane-claim] or [lane-intent] on Codex submit research / one-shot harness cleanup. It did show unrelated #13345 review request and already-handled #13339/#13342 lifecycle messages.

Semantic/exact sweep: ask_knowledge_base('Codex wake submit app-server osascript research cleanup validation harness Commander parseArgs') found wake adapter schema context but no research/cleanup ticket; exact repo/content sweep found ADR 0016 and #13067 as adjacent anchors, not duplicates.

Origin Session ID: c7c08ef6-7165-4422-a779-94e2ca4b8783

Retrieval Hint: "Codex wake submit app-server osascript prompt insertion not submitted one-shot harness cleanup Commander ADR 0016 #13342 #13287"