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	11448
title	Codify Antigravity scratch-path allowlist
state	Closed
labels	documentationenhancementdeveloper-experienceaimodel-experience
assignees	neo-gemini-pro
createdAt	May 16, 2026, 11:06 AM
updatedAt	May 16, 2026, 3:29 PM
githubUrl	https://github.com/neomjs/neo/issues/11448
author	neo-gpt
commentsCount	7
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	May 16, 2026, 3:29 PM

Codify Antigravity scratch-path allowlist

Closed Backlog/active-chunk-12 documentationenhancementdeveloper-experienceaimodel-experience

neo-gpt commented on May 16, 2026, 11:06 AM

Context

During nightshift on 2026-05-16, @tobiu reported that Gemini's Google Antigravity harness froze because it kept trying to use temporary folders that Antigravity forbids. The operator clarified this is not blame and not a personal preference; it is an MX friction item that nullified the nightshift.

The durable shape should be an Antigravity-safe scratch-path allowlist rather than a scattered blacklist of forbidden temp paths.

The Problem

Gemini/Antigravity currently lacks a compact, load-bearing rule that tells the agent where temporary or scratch artifacts may be created, or whether the harness must avoid scratch files entirely unless a path is explicitly verified.

Without an allowlist, the agent falls back to generic LLM/tooling priors: use /tmp, OS temp directories, or transient scratch folders. In this harness, that can freeze the session and silently collapse the coordination lane.

This is a systemic workflow gap, not an agent-behavior blame artifact.

The Architectural Reality

Verify-Before-Assert evidence gathered before filing:

ask_knowledge_base(query='Antigravity tmp temporary scratch folder allowlist harness freeze', type='ticket') returned no matching ticket context.
Repo grep for Antigravity.*tmp, Antigravity.*scratch, temporary folder, and related allowlist terms found no exact Antigravity scratch-path rule.
.agents/ANTIGRAVITY_RULES.md currently covers identity, architecture constraints, branch workflow, anti-reformatting, and sunset gates, but no scratch/temp path contract.
.agents/skills/debugging-antigravity/SKILL.md routes MCP duplication, sqlite workspace crash, and config-scope debugging; the payload covers MCP duplication, Chroma init deadlocks, sqlite UI crash cleanup, and fresh MCP client isolation, but no temp-folder restriction.

Substrate placement should stay Antigravity-specific. This should not bloat root AGENTS.md unless implementation proves all harnesses share the same constraint.

The Fix

Define and codify an Antigravity-safe scratch-path allowlist contract.

Expected implementation shape:

Empirically verify which path class Antigravity permits for Gemini scratch artifacts in this repo context, or confirm that the correct contract is "do not create scratch files; use repo-tracked edits and approved tools only."
Add a compact rule to .agents/ANTIGRAVITY_RULES.md if it must be loaded for every Gemini/Antigravity turn.
Add deeper troubleshooting detail to .agents/skills/debugging-antigravity/references/debugging-guide.md only if the rule needs operational recovery steps.
If a skill payload changes, preserve Progressive Disclosure: keep the router tiny and place detail in the reference payload.
Prefer the term allowlist in new substrate, with whitelist only as a search synonym if needed for legacy references.

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
Gemini/Antigravity scratch-path rule	Operator-observed nightshift freeze on 2026-05-16 plus empirical Antigravity verification	Agent only uses explicitly allowed scratch/work locations, or avoids scratch files if no safe path exists	Halt and ask/route via A2A rather than guessing `/tmp` or OS temp folders	`.agents/ANTIGRAVITY_RULES.md` and optionally `debugging-antigravity` payload	Reproduce/verify in Gemini Antigravity harness; confirm no freeze during a small lifecycle task
Antigravity debugging skill payload	Progressive Disclosure skill authoring contract	Any extended recovery/debugging detail lives in payload, not SKILL.md router	Leave SKILL.md unchanged if a one-line always-loaded rule is enough	`.agents/skills/debugging-antigravity/references/debugging-guide.md`	`node ai/scripts/lint-skill-manifest.mjs --base origin/dev` if skill files change

Acceptance Criteria

AC1: Empirically identify an Antigravity-permitted scratch/work path for Gemini in this repo context, or explicitly document that no scratch files are allowed without operator confirmation.
AC2: .agents/ANTIGRAVITY_RULES.md contains a compact always-loaded rule if the restriction must fire before any tool/file operation.
AC3: If additional troubleshooting detail is needed, debugging-antigravity receives a payload-only update; its SKILL.md router remains within Progressive Disclosure shape.
AC4: The rule is allowlist-shaped: agents use only named permitted paths/classes and do not infer safety from generic OS temp conventions.
AC5: The implementation explicitly treats this as MX friction / harness-safety, not as Gemini blame.
AC6: Validation includes a Gemini/Antigravity lifecycle smoke check showing the harness no longer freezes from temp-folder use.
AC7: The PR body cites this ticket and explains why the rule stays Antigravity-specific rather than global.

Out of Scope

Changing legitimate repo runtime/test code that uses /tmp outside the Antigravity harness context.
Globalizing the rule to Claude, Codex, or all Neo agents without evidence that those harnesses share the same restriction.
Creating a new skill unless the existing debugging-antigravity skill proves structurally insufficient.
Treating the nightshift failure as individual blame.

Avoided Traps / Gold Standards Rejected

Trap: blacklist every forbidden temp path. Rejected. A blacklist will miss the next Antigravity-forbidden location. The safe shape is an allowlist of verified permitted locations or an explicit no-scratch contract.
Trap: put a long Antigravity troubleshooting essay in always-loaded substrate. Rejected. Always-loaded substrate should contain only the rule necessary to prevent recurrence; recovery detail belongs in the skill payload.
Trap: make this global because /tmp is a common term. Rejected. The observed constraint is Google Antigravity-specific until proven otherwise.

.agents/ANTIGRAVITY_RULES.md
.agents/skills/debugging-antigravity/
Nightshift incident reported by @tobiu on 2026-05-16

Retrieval Hint: "Antigravity scratch-path allowlist tmp folder freeze Gemini harness"