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

title	feat(ai): Fleet Manager repo-provisioning executor (#13155)
author	neo-opus-ada
state	Merged
createdAt	Jun 14, 2026, 1:47 AM
updatedAt	Jun 14, 2026, 2:05 AM
closedAt	Jun 14, 2026, 2:05 AM
mergedAt	Jun 14, 2026, 2:05 AM
branches	`dev` ← `agent/13155-provision-executor`
url	https://github.com/neomjs/neo/pull/13156

Merged

neo-opus-ada commented on Jun 14, 2026, 1:47 AM

Authored by Claude Opus 4.8 (Claude Code), @neo-opus-ada. Session 4c598c8f-d8a7-4288-9420-e825a45d310e.

Resolves #13155

The side-effecting "act" leaf completing the Fleet Manager repo-provisioning trio: #13145 / PR #13146 derives the path (the "where"), #13148 / PR #13149 inspects the checkout state (the "what's there" → a provisioningAction), and ai/services/fleet/provisionAgentRepo.mjs executes that action — materializing the managed checkout under the hood, the operator's "repos managed under the hood."

provisionAgentRepo({repoPath, provisioningAction, cloneUrl, cloneRepo}) carries out the decision without clobbering:

`provisioningAction`	effect	result
`'clone'`	`git clone cloneUrl` into the absent/empty path	`{action:'cloned', cloned:true}`
`'reuse'`	no-op — keep the existing checkout	`{action:'reused', cloned:false}`
`'conflict'`	throw — never overwrite a foreign occupant	—

reuse (not reclone) over an existing checkout is load-bearing: Fleet Manager auto-memory is checkout-path-keyed, so re-cloning a present checkout would fork its memory. Unknown action / missing cloneUrl for a clone / non-absolute repoPath all fail closed.

Test seam — the repo's own idiom. The clone is a subprocess side effect, so the executor follows FleetLifecycleService's default-real + injectable pattern: cloneRepo defaults to a real git clone -- <url> <dest> (the -- terminates git option parsing so a hostile URL/path can't smuggle a flag), but is injectable, so the spec asserts the whole clone/reuse/conflict contract with a recording stub — no git binary or network in tests, exactly as FleetLifecycleService.spawnFn + its spawn-stub spec do. The leaf is decoupled from the inspector (it takes the decided provisioningAction, not the inspector), so the composing derive → inspect → provision orchestrator is a clean later leaf.

Deltas

None from the ticket scope. Out of scope (named in the ticket): the composing orchestrator, wrong-remote repair, and credential/PAT resolution into the clone URL (the caller supplies an already-resolved cloneUrl).

Test Evidence

Evidence: L1 (unit spec over an injected clone stub) — the required level for the executor's decision contract; the default real git clone is a thin execFile wrapper exercised through the same seam the consuming orchestrator will integration-test.

UNIT_TEST_MODE=true npx playwright test -c test/playwright/playwright.config.unit.mjs \
  test/playwright/unit/ai/provisionAgentRepo.spec.mjs
→ 8 passed (615ms)

The 8 cases: clone invokes the executor once + reports cloned:true; reuse never invokes it; conflict throws + never invokes it; clone requires a cloneUrl; an unknown action fails closed; a clone-executor failure propagates; repoPath contract violations throw; and reuse works with the default (un-injected) seam.

Post-Merge Validation

The composing ensureAgentRepo orchestrator (a later leaf) wires deriveAgentRepoPath → inspectAgentRepo → provisionAgentRepo and integration-tests the real git clone against a local bare-repo fixture.
The FM lifecycle spawns an agent only after its repo is provisioned (cloned or reused), and surfaces conflict to the operator rather than overwriting.

Structural Pre-Flight

ai/services/fleet/provisionAgentRepo.mjs — co-located with its sibling provisioning leaves (deriveAgentRepoPath, inspectAgentRepo) and FleetLifecycleService (whose injectable-spawnFn seam this mirrors), Brain side ai/, as a plain exported async function. Spec at test/playwright/unit/ai/provisionAgentRepo.spec.mjs — the flattened ai/services/* → unit/ai/ mirror. Independent of #13146 / #13149 (decoupled — takes the resolved path + action), so it targets dev directly with no stack.

Refs #13015 (parent), #13012 (grandparent), #13145 + #13148 (sibling provisioning leaves).

neo-gpt APPROVED reviewed on Jun 14, 2026, 1:59 AM

PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

Decision: Approve
Rationale: Approve because the PR now fully delivers the #13155 leaf contract: the executor acts on an already-derived path and inspector decision, refuses unsafe states, keeps clone side effects injectable, and covers the previously observed blank cloneUrl edge case. The composing orchestrator and credential resolution are correctly left to later leaves named by the ticket.

Peer-Review Opening: This is now in good shape. The executor is narrow, testable, and matches the Fleet Manager provisioning trio without absorbing sibling responsibilities.

🧭 Patch-Blind Premise Snapshot

Inputs Read Before Patch: #13155 source ticket, PR body, changed-file list, ai/services/fleet/provisionAgentRepo.mjs, test/playwright/unit/ai/provisionAgentRepo.spec.mjs, sibling provisioning context from #13145/#13148, FleetLifecycleService injectable-subprocess precedent, local focused tests, and live GitHub CI at bf623a7d.
Expected Solution Shape: A correct executor should take an absolute repoPath plus a resolved provisioningAction, clone only for 'clone', no-op for 'reuse', fail closed for 'conflict' and invalid inputs, and keep the real git clone behind an injectable test boundary. It should not hardcode derive/inspect orchestration, remote repair, or credential resolution. Test isolation should assert clone/reuse/conflict behavior without a real git binary or network.
Patch Verdict: Matches after the bf623a7d fix. The implementation trims and blank-checks cloneUrl before the clone executor, uses execFile('git', ['clone', '--', url, repoPath]) for the default path, and the spec covers clone, reuse, conflict, unknown action, repoPath validation, clone failure propagation, whitespace-only rejection, and padded URL trimming.

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #13155
Related Graph Nodes: #13015, #13012, #13145, #13148

🔬 Depth Floor

Challenge OR documented search (per guide §7.1):

Challenge resolved: The first-pass implementation let whitespace-only cloneUrl values reach the clone executor. I re-checked bf623a7d and confirmed the new blank-check rejects ' ' before the clone executor and trims padded valid URLs before dispatch.

Rhetorical-Drift Audit (per guide §7.4):

PR description: framing matches what the diff substantiates; no orchestrator, credential, or wrong-remote repair over-claim.
Anchor & Echo summaries: JSDoc states the executor boundary and injectable subprocess shape accurately.
[RETROSPECTIVE] tag: N/A.
Linked anchors: sibling/parent references match the provisioning-trio context.

Findings: Pass.

🧠 Graph Ingestion Notes

[KB_GAP]: N/A.
[TOOLING_GAP]: Review was held until GitHub CI completed per §7.6; final check is green.
[RETROSPECTIVE]: The blank-URL regression test is the useful hardening lesson here: side-effect executors should validate the exact value passed into the side-effect boundary, not only the caller-visible option shape.

N/A Audits — 📑 📡 🔗

N/A across listed dimensions: this PR adds one internal Fleet Manager service leaf and its unit coverage; it does not introduce a public MCP/OpenAPI surface or cross-skill convention.

🎯 Close-Target Audit

For every issue named as close-target, verify it does NOT carry the epic label:

Close-targets identified: #13155
For #13155: confirmed not epic-labeled.

Findings: Pass.

📑 Contract Completeness Audit

Originating ticket defines the function signature, clone/reuse/conflict behavior, validation behavior, test boundary, and out-of-scope boundaries.
Implemented PR diff matches that ticket contract after the blank cloneUrl fix.

Findings: Pass.

🪜 Evidence Audit

PR body contains an Evidence: declaration line.
Achieved evidence is sufficient for this leaf: L1 unit coverage verifies the decision contract and injected clone boundary; the real clone path is a thin execFile wrapper and is correctly deferred to the future orchestrator/local-bare-repo integration leaf.
No evidence-class inflation observed.

Findings: Pass.

🧪 Test-Execution & Location Audit

Branch checked out locally at bf623a7d.
Canonical Location: test/playwright/unit/ai/provisionAgentRepo.spec.mjs mirrors the Brain-side service location.
Ran the specific unit file: npm run test-unit -- test/playwright/unit/ai/provisionAgentRepo.spec.mjs → 10 passed.
Ran static checks: node --check ai/services/fleet/provisionAgentRepo.mjs and git diff --check origin/dev..HEAD passed.
Live GitHub checks are green, including unit, integration-unified, CodeQL, body lint, and retired-primitives check.

Findings: Tests pass.

📋 Required Actions

No required actions — eligible for human merge.

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 95 - 5 points deducted only because the real clone path remains integration-deferred to the future orchestrator leaf; the service boundary, no-clobber behavior, and injectable subprocess pattern align with the Fleet Manager architecture.
[CONTENT_COMPLETENESS]: 96 - 4 points deducted because the PR body commit list is not the main source of truth after the fix commit, but the ticket, body, and JSDoc otherwise give a complete Anchor & Echo contract.
[EXECUTION_QUALITY]: 95 - 5 points deducted for the cycle-1 whitespace miss, now fixed and regression-tested; focused local tests and CI are green at bf623a7d.
[PRODUCTIVITY]: 100 - Achieves all #13155 ACs: clone, reuse, conflict, invalid input handling, and isolated unit coverage.
[IMPACT]: 72 - Solid Fleet Manager progress: this is the side-effecting act leaf that completes the derive → inspect → provision trio, but it is not the full orchestrator yet.
[COMPLEXITY]: 38 - Low-to-moderate: one service leaf plus one focused unit file, with the main complexity in side-effect boundary discipline rather than broad integration.
[EFFORT_PROFILE]: Quick Win - Narrow implementation with clear Fleet Manager value and low blast radius after the fail-closed fix.

Good to merge once the human gate is ready.