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	13241
title	Codex worktrees must stay under identity-mapped roots
state	Closed
labels	documentationenhancementdeveloper-experienceaimodel-experience
assignees	neo-gpt
createdAt	Jun 14, 2026, 5:45 PM
updatedAt	Jun 14, 2026, 6:37 PM
githubUrl	https://github.com/neomjs/neo/issues/13241
author	neo-gpt
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 14, 2026, 6:37 PM

Codex worktrees must stay under identity-mapped roots

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

neo-gpt commented on Jun 14, 2026, 5:45 PM

Context

A 2026-06-14 identity-drift incident showed that Codex-authored GitHub review/comment operations can stamp the wrong GitHub account when a fresh process inherits another harness environment. We verified .codex/CODEX.md is loaded into Codex turn context through .codex/hooks.json -> .codex/hooks/codex-context.mjs, and that /Users/tobiasuhlig/.zshenv selects per-agent .env files by PWD.

Live latest-open sweep: checked latest 20 open issues immediately before filing on 2026-06-14; no equivalent Codex worktree-placement rule ticket found. A2A in-flight sweep: checked latest 30 messages immediately before filing; no competing claim on this exact scope found. Local/KB sweep: exact repository search found no existing identity-sensitive Codex worktree rule, and KB surfaced .codex/CODEX.md but no worktree/.zshenv guidance.

Release classification: boardless (Codex harness hardening follow-up; not a v13 release blocker).

The Problem

Codex currently has diagnostics for GitHub identity checks, sandboxed gh behavior, and harness restarts, but it does not instruct future Codex turns where to create review/feature worktrees. Generic scratch locations such as /private/tmp/neo-* do not match the existing .zshenv per-clone cases. If a process starts there, it may keep a stale parent environment instead of re-sourcing the Codex .env.

That creates a discipline gap: an otherwise correct Codex session can inspect or operate on a Codex worktree while a fresh child process uses another agent's GH_TOKEN / NEO_AGENT_IDENTITY.

The Architectural Reality

.codex/CODEX.md is a Codex-only turn-loaded substrate file.
.codex/hooks.json registers the UserPromptSubmit hook.
.codex/hooks/codex-context.mjs reads .codex/CODEX.md and writes it into turn context.
/Users/tobiasuhlig/.zshenv maps /Users/Shared/codex/neomjs/neo/* to the Codex .env and maps other agent clone roots to their own .env files.
Generic /private/tmp/neo-* worktrees sit outside that mapping.

The Fix

Add a compact Runtime Notes rule to .codex/CODEX.md that:

Directs Codex to create identity-sensitive worktrees under /Users/Shared/codex/neomjs/neo/.codex/worktrees/ or another path beneath /Users/Shared/codex/neomjs/neo/.
Warns against generic /private/tmp/neo-* for work that may run gh, MCP setup, PR review/comment tools, or commits.
Requires a cheap identity preflight after worktree/thread switches before state-changing GitHub actions: NEO_AGENT_IDENTITY=@neo-gpt and gh api user --jq .login == neo-gpt.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
Codex turn-loaded runtime notes	`.codex/CODEX.md` via `.codex/hooks/codex-context.mjs`	Future Codex turns use identity-mapped worktree roots for identity-sensitive work and verify identity before state-changing GitHub calls after switches.	If a scratch path is already outside the mapped root, treat it as inspect-only until identity is verified; move/create a new mapped worktree for mutations.	`.codex/CODEX.md`	Static hook/load-path verification + shell identity check.

Decision Record impact

none

Acceptance Criteria

.codex/CODEX.md contains a concise Runtime Notes rule for identity-sensitive Codex worktree placement.
The rule names an env-mapped Codex root path and explicitly warns against generic /private/tmp/neo-* for state-changing work.
The rule includes the preflight checks for NEO_AGENT_IDENTITY and gh api user --jq .login before state-changing GitHub actions after a worktree/thread switch.
The PR body documents the turn-loaded substrate placement rationale per turn-memory-pre-flight.
Verification covers the hook load path and the current neo-gpt GitHub identity.

Out of Scope

No .zshenv change in this ticket.
No GitHub Workflow MCP fail-closed implementation.
No rewrite of the broader incident runbook owned by #13239.
No cleanup of existing /private/tmp worktrees.

Avoided Traps

Do not map all /private/tmp/neo-* paths to Codex; that path family is shared-looking and can contaminate other agents.
Do not put this in global AGENTS.md; the rule is Codex-harness-local and belongs in .codex/CODEX.md.
Do not rely only on PR body self-identification; GitHub API author identity still comes from the token used by the posting process.

Related: #13239

Origin Session ID: 4ed21ddf-b92f-45ce-8689-bb3ebb563dd9

Handoff Retrieval Hints: Codex CODEX.md worktree GH_TOKEN identity drift .zshenv private tmp; identity-sensitive worktrees; 2026-06-14 agent identity drift.